***WARNING***WARNING ***WARNING***WARNING***WARNING***WARNING***WARNING***

The manual contained herein is the regular 56k family assembler manual
and thus describes certain items not supported in the software that is 
shipped with the DSP56002EVM evaluation kit.  In particular, the user
should not use any programming techniques that require the Linker.  These
references to the linker are included in this manual to allow the user to
have a more complete view of the software development tools for the 
DSP56002.  For a complete set of software development tools, the user 
should order the DSP56KCLASA (Cross-Linker-Assembler-Simulator) package. 

***WARNING***WARNING ***WARNING***WARNING***WARNING***WARNING***WARNING***

	Copywrite (c) MOTOROLA 1994
		      Semiconductor Products Sector 
		      Digital Signal Processing Division

Preface

Chapter 1

MOTOROLA DSP ASSEMBLER

1.1	INTRODUCTION 	

1.2	ASSEMBLY LANGUAGE 	

1.3	INSTALLING THE ASSEMBLER 	

1.4	RUNNING THE ASSEMBLER 	

1.5	ASSEMBLER PROCESSING 	

1.6	DEFINITION OF TERMS 	

1.7	ASSEMBLER SUPPORT FOR DIGITAL SIGNAL PROCESSING 	

Chapter 2

WRITING ASSEMBLY LANGUAGE PROGRAMS

2.1	INPUT FILE FORMAT 	

2.2	SYMBOL NAMES 	

2.3	STRINGS 	

2.4	SOURCE STATEMENT FORMAT 	

2.4.1	Label Field	 

2.4.2	Operation Field	 

2.4.3	Operand Field	 

2.4.4	(Not Applicable)

2.4.5	(Not Applicable)

2.4.6	Data Transfer Fields	 

2.4.7	Comment Field	 

2.5	ASSEMBLER OUTPUT 	

Chapter 3

 EXPRESSIONS

3.1	INTRODUCTION 	

3.2	ABSOLUTE AND RELATIVE EXPRESSIONS 	

3.3	EXPRESSION MEMORY SPACE ATTRIBUTE 	

3.4	INTERNAL EXPRESSION REPRESENTATION 	

3.5	CONSTANTS 	

3.5.1	Numeric Constants	 

3.5.2	String Constants	 

3.6	OPERATORS 	

3.6.1	Unary operators	 

3.6.2	Arithmetic operators	 

3.6.3	Shift operators	 

3.6.4	Relational operators	 

3.6.5	Bitwise operators	 

3.6.6	Logical operators	 

3.7	OPERATOR PRECEDENCE 	

3.8	FUNCTIONS 	

3.8.1	Mathematical Functions	 

3.8.2	Conversion Functions	 

3.8.3	String Functions	 

3.8.4	Macro Functions	 

3.8.5	Assembler Mode Functions	 

Chapter 4

SOFTWARE PROJECT MANAGEMENT

4.1	INTRODUCTION 	

4.2	SECTIONS 	

4.3	SECTIONS AND DATA HIDING 	

4.3.1	Sections and Symbols	 

4.3.2	Sections and Macros	 

4.3.3	Nested and Fragmented Sections	 

4.4	SECTIONS AND RELOCATION 	

4.5	ADDRESS ASSIGNMENT 	

4.5.1	The ORG Directive	 

4.5.2	Overlays	 

4.5.3	Address Assignment Examples	 

4.5.4	Circular Buffers	 

4.6	EXAMPLE 1: MULTI-PROGRAMMER ENVIRONMENT 	

4.6.1	Absolute Mode Implementation	 

4.6.2	Relative Mode Implementation	 

4.7	EXAMPLE 2: OVERLAYS 	

4.7.1	Absolute Mode Implementation	 

4.7.2	Relative Mode Implementation	 

4.8	EXAMPLE 3: BOOTSTRAP OVERLAY 	

4.8.1	Absolute Mode Implementation	 

4.8.2	Relative Mode Implementation	 

Chapter 5

MACRO OPERATIONS AND CONDITIONAL ASSEMBLY

5.1	MACRO OPERATIONS 	

5.2	MACRO LIBRARIES 	

5.3	MACRO DEFINITION 	

5.4	MACRO CALLS 	

5.5	DUMMY ARGUMENT OPERATORS 	

5.5.1	Dummy argument concatenation operator - \	 

5.5.2	Return value operator - ?	 

5.5.3	Return hex value operator - %	 

5.5.4	Dummy argument string operator - "	 

5.5.5	Macro local label override operator - ^	 

5.6	DUP, DUPA, DUPC, DUPF DIRECTIVES 	

5.7	CONDITIONAL ASSEMBLY 	

Chapter 6

ASSEMBLER SIGNIFICANT CHARACTERS AND DIRECTIVES

6.1	INTRODUCTION 	

6.2	ASSEMBLER SIGNIFICANT CHARACTERS 	

6.3	ASSEMBLER DIRECTIVES 	

6.3.1	Assembly Control	

6.3.2	Symbol Definition	 

6.3.3	Data Definition/Storage Allocation	 

6.3.4	Listing Control and Options	 

6.3.5	Object File Control	 

6.3.6	Macros and Conditional Assembly	 

6.3.7	Structured Programming	 

Chapter 7

STRUCTURED CONTROL STATEMENTS

7.1	INTRODUCTION 	

7.2	STRUCTURED CONTROL DIRECTIVES 	

7.3	SYNTAX 	

7.3.1	.BREAK Statement	 

7.3.2	.CONTINUE Statement	 

7.3.3	.FOR Statement	 

7.3.4	.IF Statement	 

7.3.5	.LOOP Statement	 

7.3.6	.REPEAT Statement	 

7.3.7	.WHILE Statement	 

7.4	SIMPLE AND COMPOUND EXPRESSIONS 	

7.4.1	Simple Expressions	 

7.4.1.1	Condition Code Expressions 	

7.4.1.2	Operand Comparison Expressions 	

7.4.2	Compound Expressions	 

7.5	STATEMENT FORMATTING 	

7.5.1	Expression Formatting	 

7.5.2	.FOR/.LOOP Formatting	 

7.5.3	Assembly Listing Format	 

7.6	EFFECTS ON THE PROGRAMMER'S ENVIRONMENT 	

Appendix A

ASCII CHARACTER CODES

Appendix B

DIRECTIVE SUMMARY

B.1	ASSEMBLY CONTROL	 

B.2	SYMBOL DEFINITION	 

B.3	DATA DEFINITION/STORAGE ALLOCATION	 

B.4	LISTING CONTROL AND OPTIONS	 

B.5	OBJECT FILE CONTROL	 

B.6	MACROS AND CONDITIONAL ASSEMBLY	 

B.7	STRUCTURED PROGRAMMING	 

Appendix C

ASSEMBLER MESSAGES

C.1	INTRODUCTION	 

C.2	COMMAND LINE ERRORS	 

C.3	WARNINGS	 

C.4	ERRORS	 

C.5	FATAL ERRORS	 

Appendix D

ASSEMBLER LISTING FILE FORMAT

D.1	INTRODUCTION	 

D.2	LISTING FILE COMMENTARY	 

D.3	CROSS-REFERENCE FORMAT	 

D.4	MEMORY UTILIZATION REPORT FORMAT	 

Appendix E

Not included in EVM 

Appendix F

Not included in EVM 

Appendix G

HOST-DEPENDENT INFORMATION

G.1	INTRODUCTION	 

G.2	DOS/386 ENVIRONMENT	 

G.2.1	Hardware Requirements	 

G.2.2	Installation	 

G.2.3	Source File Text	 

G.2.4	Invoking the Assembler	 
Notation

The notational conventions used in this manual are:

DIRECTIVE

All assembler mnemonics and directives are shown in bold upper 
case to highlight them. However, the assembler will recognize 
both upper and lower case for mnemonics and directives.

{ }

Contains a list of elements or directives, one of which must 
be selected. Each choice will be separated by a vertical bar.  
For example, {R I L} indicates that either R or L must be se-
lected.

[ ]

Contains one or more optional elements. If more than one op-
tional element is shown, the required element separators are 
indicated.  All elements outside of the angle brackets (< >) 
must be specified as they appear.  For example, the syntacti-
cal element [<number>,] requires the comma to be specified if 
the optional element <number> is selected.

< >

The element names are printed in lower case and contained in 
angle brackets.  Some common elements used to describe direc-
tives are:

<comment>			A statement comment

<label>			A statement label

<expr> or			An assembler expression
<expression>

<number>			A numeric constant

<string>			A string of ASCII characters enclosed in 
quotes

<delimiter>			A delimiter character

<option>			An assembler option

<sym> or			An assembler symbol
<symbol>



Supporting Publications

DSP56000 Family Manual. Motorola, Inc. 1992.

DSP56002 User's Manual. Motorola, Inc. 1993.

Motorola DSP Simulator Reference Manual. Motorola, Inc. 1994.

Motorola DSP Linker/Librarian Reference Manual. Motorola, Inc. 
1994.
Preface


Chapter 1

MOTOROLA DSP ASSEMBLER

1.1	  INTRODUCTION

The Motorola DSP Assemblers are programs that process assembly lan-
guage source statements written for Motorola's family of digital 
signal processors.  The assembler translates these source state-
ments into object programs compatible with other  Motorola DSP 
software and hardware products.

1.2	  ASSEMBLY LANGUAGE

The assembly language provides mnemonic operation codes for all ma-
chine instructions in the digital signal processor instruction set.  
In addition, the assembly language contains mnemonic directives 
which specify auxiliary actions to be performed by the assembler.  
These directives are not always translated into machine language.  
The assembly language enables the programmer to define and use mac-
ro instructions which replace a single statement with a predefined 
sequence of statements found in the macro definition.  Conditional 
assembly also is supported.

1.3	  INSTALLING THE ASSEMBLER

The assembler is distributed on various media and in different for-
mats depending on the host  environment.  See Appendix G, HOST-
DEPENDENT INFORMATION, for details on installing and operating the 
assembler on your particular machine.

1.4	  RUNNING THE ASSEMBLER

The general format of the command line to invoke the assembler is:

DSPASM  [options]  <filenames> 

where:

DSPASM

The name of the Motorola DSP assembler program appropri-
ate for the target processor (see Appendix F, DEVICE-DE-
PENDENT INFORMATION).  For example, for the Motorola 
DSP56000 processor the name of the assembler executable 
is ASM56000.

[options]

Any of the following command line options. These can be 
in any order, but must precede the list of source file-
names. Some options can be given more than once; the in-
dividual descriptions indicate which options may be 
specified multiple times. Option letters can be in either 
upper or lower case. 

Command options that are used regularly may be placed in 
the environment variable DSPASMOPT. If the variable is 
found in the environment the assembler adds the associ-
ated text to the existing command line prior to process-
ing any options. See your host documentation for instruc-
tions on how to define environment variables.

Option arguments may immediately follow the option let-
ter or may be separated from the option letter by blanks 
or tabs.   However, an ambiguity arises if an option 
takes an optional argument. Consider the following com-
mand line:

ASM56000  -B  MAIN  IO

In this example it is not clear whether the file MAIN is 
a source file or is meant to be an argument to the -B 
option.   If the ambiguity is not resolved the assembler 
will assume that MAIN is a source file and attempt to 
open it for reading.  This may not be what the programmer 
intended. 

There are several ways to avoid this ambiguity.  If  MAIN 
is supposed to be an argument to the -B option it can be 
placed immediately after the option letter:

ASM56000  -BMAIN  IO

If there are other options on the command line besides 
those that take optional arguments the other options can 
be placed between the ambiguous option and the list of 
source file names:

ASM56000  -B  MAIN   -V   IO

An alternative is to use two successive hyphens to indi-
cate the end of the option list:

ASM56000  -B  -- MAIN  IO

In this latter case the assembler interprets MAIN as a 
source file name and uses the default naming conventions 
for the -B option.

-A

Indicates that the assembler should run in absolute mode, 
generating an absolute object file when the -B command 
line option is given.  By default the assembler produces 
a relocatable object file that is subsequently processed 
by the Motorola DSP linker.  See Chapter 4, SOFTWARE 
PROJECT MANAGEMENT, for more information on assembler 
modes.

-B[<objfil>]

This option specifies that an object file is to be cre-
ated for assembler output.  <objfil> can be any legal 
operating system filename, including an optional path-
name.  A hyphen also may be used as an argument to indi-
cate that the object file should be sent to the standard 
output.

The type of object file produced depends on the assembler 
operation mode.  If the -A option is supplied on the com-
mand line, the assembler operates in absolute mode and 
generates an absolute object (.CLD) file.  If there is 
no -A option on the command line, the assembler operates 
in relative mode and creates a relocatable object (.CLN) 
file.

If a pathname is not specified, the file will be created 
in the current directory.  If no filename is specified, 
the assembler will use the basename (filename without ex-
tension) of the first filename encountered in the source 
input file list and append the appropriate file type 
(.CLN or .CLD) to the basename.  If the -B option is not 
specified, then the assembler will not generate an object 
file.  The -B option should be specified only once.  If 
the file named in the -B option already exists, it will 
be overwritten.

Example: ASM56000  -Bfilter  main.asm  fft.asm  fio.asm

In this example, the files MAIN.ASM, FFT.ASM, and 
FIO.ASM are assembled together to produce the relo-
catable object file FILTER.CLN.

-D<symbol>  <string>

This is equivalent to a source statement of the form:

DEFINE   <symbol>   <string>

 <string> must be preceded by a blank and should be en-
closed in single quotes if it contains any embedded 
blanks.  Note that if single quotes are used they must 
be passed to the assembler intact, e.g. some host command 
interpreters will strip single quotes from around argu-
ments. The -D<symbol> <string> sequence can be repeated 
as often as desired.  See the DEFINE directive (Chapter 
6) for more information.

Example: ASM56000  -D  POINTS  16  prog.asm

All occurrences of the symbol POINTS in the program 
PROG.ASM will be replaced by the string `16'.

-EA<errfil>

-EW<errfil>

These options allow the standard error output file to be 
reassigned on hosts that do not support error output re-
direction from the command line. <errfil> must be present 
as an argument, but can be any legal operating system 
filename, including an optional pathname.

The -EA option causes the standard error stream to be 
written to <errfil>; if <errfil> exists, the output 
stream is appended to the end of the file. The -EW option 
also writes the standard error stream to <errfil>; if 
<errfil> exists it is rewound (truncated to zero), and 
the output stream is written from the beginning of the 
file.

Example: ASM56000\x13-EWerrors\x13prog.asm

Redirect the standard error output to the file ER-
RORS. If the file already exists, it will be over-
written.

-F<argfil>

Indicates that the assembler should read command line in-
put from <argfil>.  <argfil> can be any legal operating 
system filename, including an optional pathname.   <arg-
fil> is a text file containing further options, argu-
ments, and filenames to be passed to the assembler.  The 
arguments in the file need be separated only by some form 
of white space (blank, tab, newline).  A semicolon (;) 
on a line following white space makes the rest of the 
line a comment.

The -F option was introduced to circumvent the problem 
of limited line lengths in some host system command in-
terpreters. It may be used as often as desired, including 
within the argument file itself. Command options may also 
be supplied using the DSPASMOPT environment variable. 
See the discussion of DSPASMOPT under [options] at the 
beginning of this section.

Example: ASM56000  -Fopts.cmd

Invoke the assembler and take command line options 
and source filenames from the command file 
OPTS.CMD.

-G

Send source file line number information to the object 
file.  This option is valid only in conjunction with the 
-B command line option.  The generated line number in-
formation can be used by debuggers to provide source-lev-
el debugging.

Example: ASM56000  -B -G  myprog.asm

Assemble the file MYPROG.ASM and send source file 
line number information to the resulting object 
file MYPROG.CLN.

-I<pathname>

When the assembler encounters INCLUDE files, the current 
directory (or the directory specified in the INCLUDE di-
rective) is first searched for the file.  If it is not 
found and the -I option is specified, the assembler pre-
fixes the filename (and optional pathname) specified in 
the INCLUDE directive with <pathname> and searches the 
newly formed directory pathname for the file.

The pathname must be a legal operating system pathname.  
The -I option may be repeated as many times as desired.  
The directories will be searched in the order specified 
on the command line.

Example: ASM56000  -I\project\  testprog

This example uses IBM PC pathname conventions, and 
would cause the assembler to prefix any INCLUDE 
files not found in the current directory with the 
\project\ pathname.  

-L<lstfil>

This option specifies that a listing file is to be cre-
ated for assembler output.  <lstfil> can be any legal 
operating system filename, including an optional path-
name.   A hyphen also may be used as an argument to in-
dicate that the listing file should be sent to the 
standard output, although the listing file is routed to 
standard output by default.

If a pathname is not specified, the file will be created 
in the current directory.  If no filename is specified, 
the assembler will use the basename (filename without ex-
tension) of the first filename encountered in the source 
input file list and append .LST to the basename.  If the 
-L option is not specified, then the assembler will route 
listing output to the standard output (usually the con-
sole or terminal screen) by default.  The -L option 
should be specified only once.  If the file named in the 
-L option already exists, it will be overwritten.

Example: ASM56000  -L  filter.asm  gauss.asm

In this example, the files FILTER.ASM and GAUSS.ASM 
are assembled together to produce a listing file.  
Because no filename was given with the -L option, 
the output file will be named using the basename of 
the first source file, in this case FILTER.  The 
listing file will be called FILTER.LST.

-M<pathname>

This is equivalent to a source statement of the form:

MACLIB    <pathname>

The pathname must be a legal operating system pathname.  
The -M option may be repeated as many times as desired.  
The directories will be searched in the order specified 
on the command line.  See the MACLIB directive (Chapter 
6) for more information.

Example: ASM56000  -M fftlib/  trans.asm

This example uses UNIX pathname conventions, and 
would cause the assembler to look in the fftlib sub-
directory of the current directory for a file with 
the name of the currently invoked macro found in the 
source file.

-O<opt>[,<opt>,...,<opt>]

This is equivalent to a source statement of the form:

OPT    <opt>[,<opt>,...,<opt>]

<opt> can be any of the options that are available with 
the OPT directive (see Chapter 6).  If multiple options 
are specified, they must be separated by commas.  The 
-O<opt> sequence can be repeated for as many options as 
desired.

Example: ASM56000  -OS,CRE  myprog.asm

This will activate the symbol table and cross ref-
erence listing options.

-P<proc>

Run the assembler with the specified processor revision 
level enhancements. This is for backward compatibility 
so that the assembler will flag new constructions as il-
legal. <proc> can be any of the processor identifiers 
given below. Note that if this option is not used the 
assembler runs with all latest revision level enhance-
ments on by default.

Processor			Identifier

DSP56002			56002

Example: ASM56000 \x11-P56001c \x11myprog.asm

Assemble MYPROG.ASM with the DSP56000 Revision C 
enhancements.

-Q

On some hosts the assembler displays a banner on the con-
sole when invoked.  This option inhibits the banner dis-
play.  It has no effect on hosts where the signon banner 
is not displayed by default.

Example: ASM56000  -Q  myprog.asm

Assemble the file MYPROG.ASM but do not display the 
signon banner on the console.

-R<rev>

Run the assembler without the specified processor revi-
sion level enhancements. This is for backward compati-
bility so that the assembler will flag new constructions 
as illegal. <rev> can be any of the revision specifiers 
given below, but must be appropriate for the target pro-
cessor.

This option is superseded by the -P option.

Processor			Revision

DSP56002			2

Example: ASM56000  -RC  myprog.asm

Assemble MYPROG.ASM without the DSP56000 Revision C 
enhancements.

-V

This option causes the assembler to report assembly 
progress (beginning of passes, opening and closing of in-
put files) to the standard error output stream.  This is 
useful to insure that assembly is proceeding normally.

Example: ASM56000  -V  myprog.asm

Assemble the file MYPROG.ASM and send progress 
lines to the standard error output.

-Z

This option causes the assembler to strip symbol infor-
mation from the absolute load file.  Normally symbol in-
formation is retained in the object file for symbolic 
reference purposes.  Note that this option is valid only 
when the assembler is in absolute mode via the -A command 
line option and when an object file is created (-B op-
tion).

Example: ASM56000  -A -B -Z  myprog.asm

Assemble the file MYPROG.ASM in absolute mode and 
strip symbol information from the load file created 
as output.

<filenames>

A list of operating system compatible filenames (includ-
ing optional pathnames).  If no extension is supplied for 
a given file, the assembler first will attempt to open 
the file using the filename as supplied.  If that is not 
successful the assembler appends .ASM to the filename and 
attempts to open the file again. If no pathname is spec-
ified for a given file, the assembler will look for that 
file in the current directory.  The list of files will 
be processed sequentially in the order given and all 
files will be used to generate the object file and list-
ing.

The assembler will redirect the output listing to the standard out-
put if the output listing is not suppressed with the IL option, or 
if it is not redirected via the -L command line option described 
above.  The standard output generally goes to the console or ter-
minal screen by default, but can be diverted to a file or to a 
printer by using the I/O redirection facilities of the host oper-
ating system, if available.  Error messages will always appear on 
the standard output, regardless of any option settings.  Note that 
some options (-B, -L) allow a hyphen as an optional argument which 
indicates that the corresponding output should be sent to the stan-
dard output stream.  Unpredictable results may occur if, for exam-
ple, the object file is explicitly routed to standard output while 
the listing file is allowed to default to the same output stream.

For more details on assembler operation in a particular machine 
environment see Appendix G, HOST-DEPENDENT INFORMATION.

1.5	  ASSEMBLER PROCESSING

The Motorola  DSP assembler is a two-pass assembler.  During the 
first pass the source program is read to build the symbol and macro 
tables.  During the second pass the object file is generated (as-
sembled) with reference to the tables created during pass one.  It 
is also during the second pass that the source program listing is 
produced.

Each source statement is processed completely before the next 
source statement is read.  As each line is read in, any translations 
specified by the DEFINE directive are applied.  Each statement is 
then processed, and the assembler examines the label, operation 
code, operand, and data transfer fields.  The macro definition ta-
ble is scanned for a match with the operation code.  If there is 
no match, the operation code and directive tables are scanned for 
a match with a known opcode.

Any errors detected by the assembler are displayed before the ac-
tual line containing the error is printed.  Errors and warnings are 
accumulated, and a total number of errors and warnings is printed 
at the end of the source listing.  If no source listing is produced, 
error messages are still displayed to indicate that the assembly 
process did not proceed normally.  The number of errors is returned 
as an exit status when the assembler returns control to the host 
operating system.

1.6	  DEFINITION OF TERMS

Since the Motorola DSP architectures are different from normal mi-
croprocessors, the programmer may not be familiar with some of the 
terms used in this document.  The following discussion serves to 
clarify some of the concepts discussed later in this manual.

The Motorola DSP architecture can have as many as five separate 
memory spaces referred to as the X, Y, L, P (Program), and E (EMI 
- Extended Memory Interface) memory spaces. L memory space is a 
concatenation of X and Y data memory and is considered by the as-
sembler as a superset of the X and Y memory spaces. E memory is 
specific to the DSP56004 processor, and provides for different data 
representations for various memory hardware configurations. The 
assembler will generate object code for each memory space, but ob-
ject code can only be generated for one memory space at a time.

The memory space and address location into which the object code 
generated by the assembler will be loaded are referred to as the 
load memory space and load address, respectively. Because the DSP 
architecture allows data transfers between memory spaces, some-
times object code is loaded into an address of one memory space but 
will later be transferred to a different memory space and address 
before the program is run. One example of this might be a program 
located in an external EPROM that will be transferred into external 
program RAM before it is run. The transfer of code/data from one 
memory space/address to a different memory space/address is called 
an overlay.

When the object code for a part of the program is generated that 
later will be used as an overlay, the load memory space and load 
address do not correspond to the memory space and address where the 
program will be run. The memory space and address location where 
the code/data will be located when the program is run are referred 
to as the runtime memory space and runtime address, respectively. 
If the assembler only used the load address to assign values to 
labels, then the program would not contain the correct label ref-
erences when it was transferred to the runtime memory space and the 
run-time address.

During the assembly process, the assembler uses location counters 
to record the addresses associated with the object code.  In order 
to facilitate the generation of object code for overlays, the as-
sembler maintains two different location counters, the load loca-
tion counter, which determines the address into which the object 
code will be loaded and the runtime location counter, which deter-
mines the address assigned to labels.  In addition, the assembler 
keeps track of the load memory space, which is the memory space 
into which the object code will be loaded, and the runtime memory 
space, which is the memory space to which an overlay will be trans-
ferred and the memory space attribute that will be assigned to la-
bels.  See Chapter 4, SOFTWARE PROJECT MANAGEMENT, for a practical 
discussion of the use of memory spaces and location counters.

The Motorola digital signal processors are capable of performing 
operations on modulo and reverse-carry buffers, two data structures 
useful in digital signal processing applications. The DSP assembler 
provides directives for establishing buffer base addresses, allo-
cating buffer space, and initializing buffer contents. For a buffer 
to be located properly in memory the lower bits of the starting 
address which encompass one less than the buffer size must be zero. 
For example, the lowest address greater than zero at which a buffer 
of size 32 may be located is 32 (20 hexadecimal). More generally, 
the buffer base address must be a multiple of 2k, where 2k is great-
er than or equal to the size of the buffer. Buffers can be allocated 
manually or by using the assembler buffer directives (see Chapter 
6).

The assembler operates in either absolute or relative mode, depend-
ing on the presence of the command line -A  option.  In relative 
mode the assembler creates relocatable object files.  These files 
can be combined and relocated using the Motorola DSP linker.  In 
absolute mode the assembler generates absolute object files.  Ab-
solute files cannot be relocated but can be loaded directly for 
execution.  By default the assembler runs in relative mode.

1.7	  ASSEMBLER SUPPORT FOR DIGITAL SIGNAL PROCESSING

As mentioned previously, the assembler offers facilities commonly 
found in other macro assemblers, such as nested macro capabilities, 
include files, and conditional assembly.  The assembler must also 
provide extensions in support of the unconventional architecture 
of the Motorola digital signal processors, as well as aids for pro-
gramming DSP-specific applications.  Some of these features are 
discussed briefly below; see the appropriate chapters later in this 
manual for more information.

The assembler supports the use of arbitrary algebraic expressions 
as arguments to various directives and as immediate operands in 
certain instructions.  Terms of these expressions may consist of 
the assembler's own built-in functions, which perform data conver-
sion, comparison, and computational operations.  In the digital 
signal processing domain transcendental functions for computing 
sine, cosine, and natural logarithm are useful for initializing 
data values in memory, such as sine/cosine tables for FFT algo-
rithms.  Also,  there are functions for easily converting values 
expressed in decimal floating point to their binary or fractional 
equivalents.  This conversion is done automatically for immediate 
instruction operands and arguments to the DC directive (see Chapter 
6).  See Chapter 3 for more information on assembler expressions, 
operators, and built-in functions.

The register set of the Motorola digital signal processors allows 
for efficient use of modulo and reverse-carry buffers for FFT ap-
plications.  The assembler supports this architecture by providing 
several special-purpose directives for allocating circular buff-
ers.  The BADDR, BUFFER, DSM, and DSR directives automatically ad-
vance the program counter to the next appropriate base address 
given the buffer size, and perform various boundary and magnitude 
checks to insure that the buffer is valid.  The BSM and BSR provide 
for automatic alignment and block initialization of DSP buffers.  
Since a buffer allocated in this fashion can cause alignment gaps 
in memory, the MU option (see the OPT directive, Chapter 6) may be 
used to generate a full memory utilization report.  See Chapter 6 
for more information on assembler directives and options.
Label
Opcode
Operand


Chapter 2

WRITING ASSEMBLY LANGUAGE PROGRAMS

2.1	  INPUT FILE FORMAT

Programs written in assembly language consist of a sequence of 
source statements.  Any source statement can be extended to one or 
more lines by including the line continuation character (\) as the 
last character on the line to be continued.  A source statement 
(first line and any continuation lines) can be a maximum of 255 
characters long.  Upper and lower case letters are considered 
equivalent for assembler mnemonics and directives, but are consid-
ered distinct for labels, symbols, directive arguments, and literal 
strings.

If the source file contains horizontal tabs (ASCII $09), the as-
sembler will expand these to the next fixed tab stop located at 
eight character intervals (column 1, 9, 17...), unless reset using 
the TAB directive (see Chapter 6).  This is only significant if tab 
characters are embedded within literal strings.

For more information on source input file format, see Appendix G, 
HOST-DEPENDENT INFORMATION.

2.2	  SYMBOL NAMES

Symbol names can be from one to 512 characters long.  The first 
character of a symbol must be alphabetic (upper or lower case); any 
remaining characters can be either alphanumeric (A-Z, a-z, 0-9) or 
the underscore character (_).  Upper and lower case letters in sym-
bols are considered distinct unless the IC option is in effect (see 
the OPT directive, Chapter 6).

Valid:	loop_1	Invalid:	1_loop
	ENTRY		loop.e
	a_B_c

Certain identifiers are reserved by the assembler and cannot be 
used.  These identifiers are the upper or lower case name of any 
Motorola DSP processor register.  See Appendix F for a list of the 
register names of the appropriate target processor.

2.3	  STRINGS

One or more ASCII characters enclosed by single quotes (') consti-
tute a literal ASCII string.  In order to specify an apostrophe 
within a literal string, two consecutive apostrophes must appear 
where the single apostrophe is intended.  Strings are used as op-
erands for some assembler directives and also can be used to a lim-
ited extent in expressions.

A string may also be enclosed in double quotes (") in which case 
any DEFINE directive symbols contained in the string would be ex-
panded. The double quote should be used with care inside macros 
since it is used as a dummy argument string operator (see Chapter 
5). In that case the macro concatenation operator can be used to 
escape the double-quoted string if desired.

Two strings separated by the string concatenation operator (++) 
will be recognized by the assembler as equivalent to the concate-
nation of the two strings.  For example, these two strings are 
equivalent:

'ABC'++'DEF'  =  'ABCDEF'

The assembler has a substring extraction capability using the 
square brackets ([ ]). Here is an example:

['DSP56000',3,5]  =  '56000'

Substrings may be used wherever strings are valid and can be nest-
ed.  There are also functions for determining the length of a string 
and the position of one string within another.  See Chapter 3 for 
more information on string functions.

2.4	  SOURCE STATEMENT FORMAT

Each source statement may include up to six fields separated 
by one or more spaces or tabs: a label field, an operation 
field, an operand field,  up to two data transfer fields, and 
a comment field.  Only fields preceding the comment field are con-
sidered significant to the assembler; the comment field is ignored.  
For example, the following source statement shows all six possi-
ble fields for the DSP56002:

LOOP	MAC X0,Y0,A	x:(r0)+,x0	y:(r4)+,y0	;TEXT

In general, the contents of each field other than the comment field 
cannot contain embedded whitespace characters, since these charac-
ters are used as field delimiters.  Two exceptions are blanks and 
tabs in quoted strings and the syntax of structured control state-
ments (see Chapter 7).

2.4.1	  Label Field

The label field occurs as the first field of a source statement, 
and can take one of the following forms:

1.	A space or tab as the first character on a line ordinarily 
indicates that the label field is empty, and that the line 
has no label.

2.	An alphabetic character as the first character indicates 
that the line contains a symbol called a label.

3.	An underscore (_) as the first character indicates that the 
label is a  local label.

Labels may be indented if the label symbol is immediately followed 
by a colon (:).  If the first non-blank field on a line complies 
with either forms 2 or 3 above and the field ends with a colon, the 
assembler regards this as the label field, even if it does not start 
with the first character on the line.  However, all characters pre-
ceding the label on the source line must be whitespace characters 
(spaces or tab characters).  There should be no intervening blanks 
or tabs between the end of the label symbol and the appended colon 
character.

Local labels are any normal symbol name preceded (with no inter-
vening blanks) by an underscore (_).  Except for the special case 
of macros (described below), local labels have a limited scope 
bounded by any two non-local labels.  The local label can be re-
ferred to or defined only in source statements that are between two 
source lines containing non-local labels.  Local labels are useful 
in defining program locations where a unique label name is required 
but is not considered useful in documenting the source file (for 
example, the terminating address of a DO loop).  Note that the max-
imum length of a local label includes the leading underscore (_) 
character.

Use of local labels in macros represents a special case.  All local 
labels within a macro are considered distinct for the currently 
active level of macro expansion (unless the macro local label over-
ride operator is used; see Chapter 5).  These local labels are valid 
for the entire macro expansion and are not considered bounded by 
non-local labels.  Therefore, all local labels within a macro must 
be unique.  This mechanism allows the programmer to freely use lo-
cal labels within a macro definition without regard to the number 
of times that the macro is expanded.  Non-local labels within a 
macro expansion are considered to be normal labels and therefore 
cannot occur more than once unless used with the SET directive (see 
Chapter 6).

A label may occur only once in the label field of an individual 
source file unless it is used as a local label, a label local to a 
section, or is used with the SET directive.  If a non-local label 
does occur more than once in a label field, each reference to that 
label after the first will be flagged as an error.

A line consisting of a label only is a valid line and has the effect 
of assigning the value of the location counter to the label.  With 
the exception of some directives, a label is assigned the value of 
the location counter of the first word of the instruction or data 
being assembled.

2.4.2	  Operation Field

The operation field appears after the label field, and must be pre-
ceded by at least one space or tab.  Entries in the operation field 
may be one of three types:

Opcode	-	Mnemonics that correspond directly to DSP machine 
instructions.

Directive	-	Special operation codes known to the assembler 
which control the assembly process.

Macro call	-	Invocation of a previously defined macro which is 
to be inserted in place of the macro call.

The assembler first searches for operation codes in an internal 
macro definition table.  If no match is found, the table of machine 
operation codes and assembler directives is searched.  If neither 
of the tables holds the specified operation code, an error message 
is generated  (this sequence can be altered with the MACLIB direc-
tive).  Macro names can therefore replace standard machine opera-
tion codes and assembler directives, although a warning will be 
issued  if such a replacement occurs.  The warning can be avoided 
by use of the RDIRECT directive.  See Chapter 6 for more information 
on the MACLIB and RDIRECT directives.

2.4.3	  Operand Field

The interpretation of the operand field is dependent on the con-
tents of the operation field.  The operand field, if present, must 
follow the operation field, and must be preceded by at least one 
space or tab.  The operand field may contain a symbol, an expres-
sion, or a combination of symbols and expressions separated by com-
mas.  There should be no intervening whitespace characters 
separating operand elements.

 The operand field of machine instructions is used to specify the 
addressing mode of the instruction, as well as the operand of the 
instruction.  The format of the operand field for a particular in-
struction is given in Appendix A of the User Manual for the DSP in 
question (.e.g. DSP56000/DSP56001 User's Manual).  The operand 
fields of assembler directives are described in Chapter 6.  The 
operand fields of macros (Chapter 5) depend on the definition of 
the macro.

2.4.4	  Operation 2 Field

(DSP96000 only--This feature is not supported on the 56k family.)

2.4.5	  Operand 2 Field

(DSP96000 only--This feature is not supported on the 56k family.)

2.4.6	  Data Transfer Fields

Most opcodes can specify one or more data transfers to occur during 
the execution of the instruction.  These data transfers are indi-
cated by two addressing mode operands separated by a comma, with 
no embedded blanks.  If two data transfers are specified, they must 
be separated by one or more blanks or  tabs.  See the appropriate 
DSP User's Manual for a complete discussion of addressing modes 
that are applicable to data transfer specifications.

2.4.7	  Comment Field

Comments are not considered significant to the assembler, but can 
be included in the source file for documentation purposes. A com-
ment field is composed of any characters (not part of a literal 
string) that are preceded by a semicolon (;). A comment starting 
in the first column of the source file will be aligned with the 
label field in the listing file. Otherwise, the comment will be 
shifted right and aligned with the comment field in the listing 
file, unless the NOPP option is used (see the OPT directive, Chap-
ter 6). Comments preceded by two consecutive semicolons (;;) will 
not be reproduced on the assembler listing and will not be saved 
as part of a macro definition.

2.5	  ASSEMBLER OUTPUT

The assembler output consists of an optional listing of the source 
program and an optional object file.  Appendix D contains the de-
scription of the source listing format and Appendix E contains the 
description of the object file format.

The assembly source program listing contains the original source 
statements, formatted for easier reading, as well as additional in-
formation which is generated by the assembler.  Most lines in the 
listing correspond directly to a source statement.  Lines which do 
not correspond directly to source statements include page headings, 
error messages, and expansions of macro calls or directives such 
as DC (Define Constant; see Chapter 6).

The assembly listing optionally may contain a symbol table or a 
cross-reference table of all non-local symbols appearing in the 
program.  These are always printed after the end of source input 
or the END directive (whichever occurs first) if either the symbol 
table or cross-reference table options are in effect (see the OPT 
directive, Chapter 6).  The symbol table contains the name of each 
symbol, along with its defined value.  The cross-reference table 
additionally contains the assembler-maintained source line number 
of every reference to every non-local symbol (local symbols may be 
included in the cross-reference listing by using the LOC option; 
see the OPT directive, Chapter 6).  The format of the cross- ref-
erence table is shown in Appendix D.

If the MU option is enabled (see the OPT directive, Chapter 6), the 
assembler generates a report of load and runtime memory utiliza-
tion.  The report shows beginning and ending addresses of allocated 
memory areas, along with their lengths and associated symbol names, 
if applicable.  A separate report is generated for each memory 
space where data has been reserved for use by the program.  The 
format of the report is given in Appendix D.

The assembler object file is a binary COFF (Common Object File For-
mat) file, with extensions and adaptations to support symbolic de-
bugging and  to make DSP object files transportable among host 
platforms.  COFF is a formal definition for the structure of ma-
chine code files.  It is derived from AT&T Unix System V and rep-
resents a quasi-de facto standard for object file formats.  Refer 
to Appendix E for more information on Motorola DSP COFF structure 
and layout.
Opcode 2
Operand 2
X field
Y field
Comment


Chapter 3

 EXPRESSIONS

3.1	  INTRODUCTION

An expression represents a value which is used as an operand in an 
assembler instruction or directive.  An expression is a combination 
of symbols, constants, operators, and parentheses.  Expressions may 
contain user-defined labels and their associated integer or float-
ing point values, and/or any combination of integers, floating 
point numbers, or ASCII literal strings.  In general, white space 
(a blank or tab) is not allowed between the terms and operators of 
an assembler expression.  Expressions otherwise follow the conven-
tional rules of algebra and boolean arithmetic.

3.2	  ABSOLUTE AND RELATIVE EXPRESSIONS

An expression may be either relative or absolute.  An absolute ex-
pression is one which consists only of absolute terms, or is the 
result of two relative terms with opposing signs.  A relative ex-
pression consists of a relative term by itself or only in combina-
tion with absolute terms.

When the assembler is operating in relative mode all address ex-
pressions must adhere to the above definitions for absolute or rel-
ative expressions.  This is because only these types of expressions 
will retain a meaningful value after program relocation.  For ex-
ample, when relative terms are paired with opposing signs, the re-
sult is the difference between the two relative terms, which is an 
absolute value.  However, if two positive relative terms are added 
together the result is unpredictable based on the computed values 
of the terms at relocation time.

3.3	  EXPRESSION MEMORY SPACE ATTRIBUTE

A symbol is associated with either an integer or a floating point 
value which is used in place of the symbol during the expression 
evaluation.  Each symbol also carries a memory space attribute of 
either X, Y, L, Program, EMI, or None.  SET labels, constants, and 
floating point expressions always have a memory space attribute of 
None.  The result of an expression will always have a memory space 
attribute associated with it.  The unary logical negate operator, 
relational operators, and some functions return values that have a 
memory space attribute of N.  The result of an expression that has 
only one operand (and possibly the unary negate or unary minus op-
erator) always has the memory attribute of that operand.  Expres-
sions that involve two or more operands and operators other than 
those mentioned above derive the memory space attribute of the re-
sult by examining the operands on the left and right side of an 
operator as shown in the following chart:

		Left Operand Memory Space Attribute
     
			X	Y	L	P	E	N

Right Operand	X	X	*	X	*	*	X
Memory Space
Attribute	Y	*	Y	Y	*	*	Y

		L	X	Y	L	*	*	L

		P	*	*	*	P	*	P

		E	*	*	*	*	E	E

		N	X	Y	L	P	E	N

* = Represents an illegal operation that will result in an error.

Notice that L memory space is regarded as a union of both X and Y 
space.  In expressions that have one element that has a memory space 
attribute of L and another element with a memory space attribute 
of either X or Y, the result will have the more restrictive memory 
space attribute (X or Y).

The memory space attribute is regarded by the assembler as a type, 
in the same sense that high level languages use type for variables. 
Symbols that are assigned memory space attributes of X, Y, L, P, 
or E are assumed to be addresses and therefore can only have values 
between zero and the maximum address value of the DSP inclusive. 
Only symbols that have a memory space attribute of N can have values 
greater than the maximum address of the target processor.

Memory space attributes become important when an expression is used 
as an address.  Errors will occur when the memory space attribute 
of the expression result does not match the explicit or implicit 
memory space specified in the source code.  Memory spaces are ex-
plicit when the address has any of the following forms:

X:<address expression> 
Y:<address expression>
L:<address expression>
P:<address expression>
E:<address expression>

The memory space is implicitly P when an address is used as the 
operand of a DO, branch, or jump-type instruction.

Expressions used for immediate addressing can have any memory space 
attribute.

3.4	  INTERNAL EXPRESSION REPRESENTATION

Expression value representation internal to the assembler is de-
pendent on the word size of the target processor.  The assembler 
supports a word and a double word integer format internally.  The 
actual storage size of an expression value is dependent upon the 
magnitude of the result, but the assembler is capable of represent-
ing signed integers up to 64 bits in length.  These longer integer 
representations are useful when performing data initialization in 
L memory space.

Internal floating point representation is almost entirely depen-
dent upon the host environment, but in general floating point val-
ues are stored in double precision format.  This means that there 
are ordinarily 64 bits of storage allotted for a floating point 
number by the assembler, with 11 bits of exponent, 53 bits of man-
tissa, and an implied binary point.

3.5	  CONSTANTS

Constants represent quantities of data that do not vary in value 
during the execution of a program.  

3.5.1	  Numeric Constants

Numeric constants can be in one of three bases:

Binary	Binary constants consist of a percent sign (%) 
followed by a string of binary digits (0,1).

Example:	%11010

Hexadecimal	Hexadecimal constants consist of a dollar sign 
($) followed by a string of hexadecimal digits 
(0-9, A-F, a-f).

Example:	$12FF, $12ff

Decimal	Decimal constants can be either floating point or 
integer.  Integer decimal constants consist of a 
string of decimal (0-9) digits optionally preced-
ed by a grave accent  (`).  Floating point con-
stants are indicated either by a preceding, 
following, or included decimal point or by the 
presence of an upper or lower case `E' followed 
by the exponent.

Example:

12345	(integer)
6E10	(floating point)
.6	(floating point)
2.7e2	(floating point)

A constant may be written without a leading radix indicator if the 
input radix is changed using the RADIX directive.  For example, a 
hexadecimal constant may be written without the leading dollar sign 
($) if the input radix is set to16 (assuming an initial radix of 
10).  The default radix is10.  See Chapter 6 on the RADIX directive 
for more information.

3.5.2	  String Constants

String constants that are used in expressions are converted to a 
concatenated sequence of ASCII bytes (right aligned), as shown be-
low.  Strings used in expressions are limited to the long word size 
of the target processor; subsequent characters in the string are 
ignored.  Null strings (strings that have no characters) have a 
value of 0.

String constants greater than the maximum number of characters can 
be used in expressions, but the assembler will truncate the value 
and will use only those characters that will fit in a DSP long word.  
In this case, a warning will be printed.  This restriction also 
applies to string constants using the string concatenation opera-
tor.  Handling of string constants by the DC and DCB directives is 
an exception to this rule; see Chapter 6 for a description.

Examples:

'ABCD'	($41424344)
'''79'	($00273739)
'A'	($00000041)
''	($00000000) - null string
'abcdef'	($61626364)
'abc'++'de'	($61626364)

3.6	  OPERATORS

Some of the assembler operators can be used with both floating 
point and integer values.  If one of the operands of the operator 
has a floating point value and the other has an integer value, the 
integer will be converted to a floating point value before the op-
erator is applied and the result will be floating point.  If both 
operands of the operator are integers, the result will be an inte-
ger value.  Similarly, if both the operands are floating point, the 
result will be a floating point value.

3.6.1	  Unary operators

plus	(+)
minus	(-)
one's complement	(~)	- Integer only
logical negate	(!)

The unary plus operator returns the value of its operand.

The unary minus operator returns the negative of its operand.

The one's complement operator returns the one's complement of its 
operand.  It cannot be used with a floating point operand.

The unary logical negation operator returns an integer 1 (memory 
space attribute None) if the value of its operand is 0 and will 
return a 0 otherwise. For example, if the symbol BUF had a value 
of 0, then !BUF would have a value of 1. If BUF had a value of 1000, 
!BUF would have a value of 0.

3.6.2	  Arithmetic operators

addition	(+)
subtraction	(-)
multiplication	(*)
division	(/)
mod	(%)

The addition operator yields the sum of its operands.

The subtraction operator yields the difference of its operands.

The multiplication operator yields the product of its operands.

The divide operator yields the quotient of the division of the 
first operand by the second.  For integer operands the divide op-
eration will produce a truncated integer result.

The mod operator applied to integers will yield the remainder from 
the division of the first operand by the second.  If the mod oper-
ator is used with floating point operands, the mod operator will 
apply the following rules:

Y % Z 	= Y	if Z = 0
	= X	if Z <> 0

where X has the same sign as Y, is less than Z, and satisfies the 
relationship:

Y = i * Z + X

where i is an integer.

3.6.3	  Shift operators

shift left	(<<)	- Integer only
shift right	(>>)	- Integer only

The shift left operator causes the left operand to be shifted to 
the left (and zero-filled) by the number of bits specified by the 
right operand.

The shift right operator causes the left operand to be shifted to 
the right by the number of bits specified by the right operand.  
The sign bit will be extended.

Shift operators cannot be applied to floating point operands.

3.6.4	  Relational operators

less than	(<)
less than or equal	(<=)
greater than	(>)
greater than or equal	(>=)
equal	(==)
not equal	(!=)

Relational operators all work the same way.  If the indicated con-
dition is true, the result of the expression is an integer 1.  If 
it is false, the result of the expression is an integer 0.  In 
either case, the memory space attribute of the result is None.

For example, if D has a value of 3 and E has a value of 5, then the 
result of the expression D<E is 1, and the result of the expression 
D>E is 0.  Each operand of the conditional operators can be either 
floating point or integer.  Test for equality involving floating 
point values should be used with caution, since rounding error 
could cause unexpected results.  Relational operators are primarily 
intended for use with the conditional assembly IF directive, but 
can be used in any expression.

3.6.5	  Bitwise operators

AND	(&)	- Integer only
OR	(|)	- Integer only
exclusive OR	(^)	- Integer only

The bitwise AND operator yields the bitwise AND function of its 
operands.

The bitwise OR operator yields the bitwise OR function of its op-
erands.

The bitwise exclusive OR operator yields the bitwise exclusive OR  
function of its operands.

Bitwise operators cannot be applied to floating point operands.

3.6.6	  Logical operators

Logical AND	(&&)
Logical OR	(||)

The logical AND operator returns an integer 1 if both of its oper-
ands are nonzero; otherwise, it returns an integer 0.

The logical OR operator returns an integer 1 if either of its op-
erands is nonzero; otherwise it returns an integer 0.

The types of the operands may be either integer or floating point; 
the memory space attribute of the result is None.  Logical opera-
tors are primarily intended for use with the conditional assembly 
IF directive, but can be used in any expression.

3.7	  OPERATOR PRECEDENCE

Expressions are evaluated with the following operator precedence:

1.  parenthetical expression (innermost first)
2.  unary plus, unary minus, one's complement, logical nega-
tion
3.  multiplication, division, mod
4.  addition, subtraction
5.  shift
6.  relational operators:   less, less or equal, greater, 
greater or equal
7.  relational operators:  equal, not equal
8.  bitwise AND, OR, EOR
9.  logical AND, OR

Operators of the same precedence are evaluated left to right.  Val-
id operands include numeric constants, literal ASCII strings, and 
symbols.  The one's complement, shift, and bitwise operators cannot 
be applied to floating point operands.  That is, if the evaluation 
of an expression (after operator precedence has been applied) re-
sults in a floating point number on either side of any of these 
operators, an error will be generated.

3.8	  FUNCTIONS

The assembler has several built-in functions to support data con-
version, string comparison, and transcendental math computations.  
Functions may be used as terms in any arbitrary expression.  Func-
tions may have zero or more arguments, but must always be followed 
by open and closed parentheses.  Function arguments which are ex-
pressions must be absolute expressions except where noted.  Argu-
ments containing external references are not allowed.  There must 
be no intervening spaces between the function name and the opening 
parenthesis, and there must be no spaces between comma-separated 
arguments.

Assembler functions can be grouped into five types:

1.  Mathematical functions
2.  Conversion functions
3.  String functions
4.  Macro functions
5.  Assembler mode functions

3.8.1	  Mathematical Functions

The mathematical functions comprise transcendental, random value, 
and min/max functions, among others:

ABS	- Absolute value
ACS	- Arc cosine
ASN 	- Arc sine
AT2	- Arc tangent
ATN	- Arc tangent
CEL	- Ceiling function
COH	- Hyperbolic cosine
COS	- Cosine
FLR	- Floor function
L10	- Log base 10
LOG	- Natural logarithm
MAX	- Maximum value
MIN	- Minimum value
POW	- Raise to a power
RND	- Random value
SGN	- Return sign
SIN	- Sine
SNH	- Hyperbolic sine
SQT	- Square root
TAN	- Tangent
TNH	- Hyperbolic tangent
XPN	- Exponential function

3.8.2	  Conversion Functions

The conversion functions provide conversion between integer, 
floating point, and fixed point fractional values:

CVF	- Convert integer to floating point
CVI	- Convert floating point to integer
CVS	- Convert memory space
FLD	- Shift and mask operation
FRC	- Convert floating point to fractional
LFR	- Convert floating point to long fractional
LNG	- Concatenate to double word
LUN	- Convert long fractional to floating point
RVB	- Reverse bits in field
UNF	- Convert fractional to floating point

3.8.3	  String Functions

String functions compare strings, return the length of a string, 
and return the position of a substring within a string:

LEN	- Length of string
POS	- Position of substring in string
SCP	- Compare strings

3.8.4	  Macro Functions

Macro functions return information about macros:

ARG	- Macro argument function
CNT	- Macro argument count
MAC	- Macro definition function
MXP	- Macro expansion function

3.8.5	  Assembler Mode Functions

Miscellaneous functions having to do with assembler operation:

CCC	- Cumulative cycle count
CHK	- Current instruction/data checksum
CTR	- Location counter type
DEF	- Symbol definition function
EXP	- Expression check
INT	- Integer check
LCV	- Location counter value
LST	- LIST directive flag value
MSP	- Memory space
REL	- Relative mode function

Individual descriptions of each of the assembler functions follow.  
They include usage guidelines, functional descriptions, and exam-
ples.

@ABS(<expression>)

Returns the absolute value of <expression> as a floating point 
value.  The memory space attribute of the result will be None.

Example:

MOVE	#@ABS(VAL),D4.S		; load absolute value

@ACS(<expression>)

Returns the arc cosine of <expression> as a floating point 
value in the range zero to pi.  The result of <expression> 
must be between -1 and 1.  The memory space attribute of the 
result will be None.

Example:

ACOS	=	@ACS(-1.0)	; ACOS  =  3.141593

@ARG(<symbol> | <expression>)

Returns integer 1 if the macro argument represented by <sym-
bol> or <expression> is present, 0 otherwise.  If the argument 
is a symbol it must be single-quoted and refer to a dummy ar-
gument name.  If the argument is an expression it refers to 
the ordinal position of the argument in the macro dummy argu-
ment list.  A warning will be issued if this function is used 
when no macro expansion is active.  The memory space attribute 
of the result will be None.

Example:

IF	@ARG(TWIDDLE)		; twiddle factor pro-
vided?

@ASN(<expression>)

Returns the arc sine of <expression> as a floating point value 
in the range -pi/2 to pi/2.  The result of <expression> must 
be between -1 and 1.  The memory space attribute of the result 
will be None.

Example:

ARCSINE	SET	@ASN(-1.0)	; ARCSINE  =  -
1.570796

@AT2(<expr1,expr2>)

Returns the arc tangent of <expr1>/<expr2> as a floating point 
value in the range -pi to pi.  Expr1 and expr2 must be sepa-
rated by a comma.  The memory space attribute of the result 
will be None.

Example:

ATAN	EQU	@AT2(-1.0,1.0)	; ATAN  =  -0.7853982

@ATN(<expression>)

Returns the arc tangent of <expression> as a floating point 
value in the range -pi/2 to pi/2.  The memory space attribute 
of the result will be None.

Example:

MOVE	#@ATN(1.0),D0.S	; load arc tangent

@CCC()

Returns the cumulative cycle count as an integer.  Useful in 
conjunction with the CC, NOCC, and CONTCC assembler options 
(see the OPT directive).  The memory space attribute of the 
result will be None.

Example:

IF	@CCC() > 200	; cycle count > 200?

@CEL(<expression>)

Returns a floating point value which represents the smallest 
integer greater than or equal to <expression>.  The memory 
space attribute of the result will be None.

Example:

CEIL	SET	@CEL(-1.05)	; CEIL  =  -1.0

@CHK()

Returns the current instruction/data checksum value as an in-
teger.  Useful in conjunction with the CK, NOCK, and CONTCK 
assembler options (see the OPT directive).  Note that assign-
ment of the checksum value with directives other than SET 
could cause phasing errors due to different generated instruc-
tion values between passes.  The memory space attribute of the 
result will be None.

Example:

CHKSUM	SET	@CHK()	; reserve checksum 
value

@CNT()

Returns the count of the current macro expansion arguments as 
an integer.  A warning will be issued if this function is used 
when no macro expansion is active.  The memory space attribute 
of the result will be None.

Example:

ARGCNT	SET	@CNT()	; squirrel away arg 
count

@COH(<expression>)

Returns the hyperbolic cosine of <expression> as a floating 
point value.  The memory space attribute of the result will 
be None.

Example:

HYCOS	EQU	@COH(VAL)	; compute hyperbolic 
cosine

@COS(<expression>)

Returns the cosine of <expression> as a floating point value.  
The memory space attribute of the result will be None.

Example:

DC	-@COS(@CVF(COUNT)*FREQ)	; compute cosine value

@CTR({L | R})

If L is specified as the argument, returns the counter number 
of the load location counter.  If R is specified, returns the 
counter number of the runtime location counter.  The counter 
number is returned as an integer value with memory space of 
None.

Example:

CNUM	=	@CTR(R)	; runtime counter num-
ber

@CVF(<expression>)

Converts the result of <expression> to a floating point value.  
The memory space attribute of the result will be None.

Example:

FLOAT	SET	@CVF(5)	; FLOAT  =  5.0

@CVI(<expression>)

Converts the result of <expression> to an integer value.  This 
function should be used with caution since the conversions can 
be inexact (e.g., floating point values are truncated).  The 
memory space attribute of the result will be None.

Example:

INT	SET	@CVI(-1.05)	; INT  =  -1

@CVS({X | Y | L | P | E | N},<expression>)

Converts the memory space attribute of <expression> to that 
specified by the first argument; returns <expression>.  See 
section 3.3 for more information on memory space attributes.  
The <expression> may be relative or absolute.

Example:

LOADDR	EQU	@CVS(X,TARGET)	; set LOADDR to X:TAR-
GET

@DEF(<symbol>)

Returns an integer 1 (memory space attribute N) if <symbol> 
has been defined, 0 otherwise.  <symbol> may be any label not 
associated with a MACRO or SECTION directive.  If <symbol> is 
quoted it is looked up as a DEFINE symbol; if it is not quoted 
it is looked up as an ordinary label.

Example:

IF	@DEF(ANGLE)	; assemble if ANGLE 
defined

@EXP(<expression>)

Returns an integer 1 (memory space attribute N) if the eval-
uation of <expression> would not result in errors.  Returns 0 
if the evaluation of <expression> would cause an error.  No 
error will be output by the assembler if <expression> contains 
an error.  No test is made by the assembler for warnings.  The 
<expression> may be relative or absolute.

Example:

IF	!@EXP(@FRC(VAL))	; skip on error

@FLD(<base>,<value>,<width>[,<start>])

Shift and mask <value> into <base> for <width> bits beginning 
at bit <start>.  If <start> is omitted, zero (least signifi-
cant bit) is assumed.  All arguments must be positive integers 
and none may be greater than the target word size.  Returns 
the shifted and masked value with a memory space attribute of 
None.

Example:

SWITCH	EQU	@FLD(TOG,1,1,7)	; turn eighth bit on

@FLR(<expression>)

Returns a floating point value which represents the largest 
integer less than or equal to <expression>.  The memory space 
attribute of the result will be None.

Example:

FLOOR	SET	@FLR(2.5)	; FLOOR  =  2.0

@FRC(<expression>)

For binary fractional DSPs (DSP56000) this functions performs 
scaling and convergent rounding to obtain the fractional rep-
resentation of the floating point <expression> as an integer.  

Example:

FRAC	EQU	@FRC(FLT)+1	; compute saturation

@INT(<expression>)

Returns an integer 1 (memory space attribute N) if <expres-
sion> has an integer result, 0 otherwise.  The <expression> 
may be relative or absolute.

Example:

IF	@INT(TERM)	; insure integer value

@L10(<expression>)

Returns the base 10 logarithm of <expression> as a floating 
point value.  <expression> must be greater than zero.  The 
memory space attribute of the result will be None.

Example:

LOG	EQU	@L10(100.0)	; LOG  =  2

@LCV({L | R}[,{L | H | <expression>}])

If L is specified as the first argument, returns the memory 
space attribute and value of the load location counter.  If R 
is specified, returns the memory space attribute and value of 
the runtime location counter.  The optional second argument 
indicates the Low, High, or numbered counter and must be sep-
arated from the first argument by a comma.  If no second ar-
gument is present the default counter (counter 0) is assumed.

The @LCV function will not work correctly if used to specify 
the runtime counter value of a relocatable overlay.  This is 
because the resulting value is an overlay expression, and 
overlay expressions may not be used to set the runtime counter 
for a subsequent overlay.  See the ORG directive (Chapter 6) 
for more information.

Example:

ADDR	=	@LCV(R)	; save runtime address

@LEN(<string>)

Returns the length of <string> as an integer.  The memory 
space attribute of the result will be None.

Example:

SLEN	SET	@LEN('string')	; SLEN  =  6

@LFR(<expression>)

For binary fractional DSPs (DSP56000) this functions performs 
scaling and convergent rounding to obtain the fractional rep-
resentation of the floating point <expression> as a long in-
teger.  

Example:

LFRAC	EQU	@LFR(LFLT)	; store binary form

@LNG(<expr1>,<expr2>)

Concatenates the single word <expr1> and <expr2> into a double 
word value such that <expr1> is the high word and <expr2> is 
the low word.  The memory space attribute of the result will 
be None.

Example:

LWORD	DC	@LNG(HI,LO)	; build long word

@LOG(<expression>)

Returns the natural logarithm of <expression> as a floating 
point value.  <expression> must be greater than zero.  The 
memory space attribute of the result will be None.

Example:

LOG	EQU	@LOG(100.0)	; LOG  =  4.605170

@LST()

Returns the value of the LIST directive flag as an integer, 
with a memory space attribute of None.  Whenever a LIST di-
rective is encountered in the assembler source, the flag is 
incremented; when a NOLIST directive is encountered, the flag 
is decremented.

Example:

DUP	@CVI(@ABS(@LST()))	; list unconditional-
ly

@LUN(<expression>)

Converts the double-word <expression> to a floating point val-
ue.  For fractional DSPs (DSP56000) <expression> should rep-
resent a binary fraction.  

Example:

DBLFRC	EQU	@LUN($3FE0000000000000)	;DBLFRC  =  0.5

@MAC(<symbol>)

Returns an integer 1 (memory space attribute N) if <symbol> 
has been defined as a macro name, 0 otherwise.

Example:

IF	@MAC(DOMUL)	; expand macro

@MAX(<expr1>[,...,<exprN>])

Returns the greatest of <expr1>,...,<exprN> as a floating 
point value.  The memory space attribute of the result will 
be None.

Example:

MAX	DC	@MAX(1.0,5.5,-3.25)	; MAX  =  5.5

@MIN(<expr1>[,...,<exprN>])

Returns the least of <expr1>,...,<exprN> as a floating point 
value.  The memory space attribute of the result will be None.

Example:

MIN	DC	@MIN(1.0,5.5,-3.25)	; MIN  =  -3.25

@MSP(<expression>)

Returns the memory space attribute of <expression> as an in-
teger value:

None	= 0
X space	= 1
Y space	= 2
L space	= 3
P space	= 4
E space	= 5

The <expression> may be relative or absolute.

Example:

MEM	SET	@MSP(ORIGIN)	; save memory space

@MXP()

Returns an integer 1 (memory space attribute N) if the assem-
bler is expanding a macro, 0 otherwise.

Example:

IF	@MXP()	; macro expansion ac-
tive?

@POS(<str1>,<str2>[,<start>])

Returns the position of string <str2> in <str1> as an integer, 
starting at position <start>.  If <start> is not given the 
search begins at the beginning of <str1>.  If the <start> ar-
gument is specified it must be a positive integer and cannot 
exceed the length of the source string.  The memory space at-
tribute of the result will be None.

Example:

ID	EQU	@POS('DSP56000','56')	; ID  =  3

@POW(<expr1>,<expr2>)

Returns <expr1> raised to the power <expr2> as a floating 
point value.  <expr1> and <expr2> must be separated by a com-
ma.  The memory space attribute of the result will be None.

Example:

BUF	EQU	@CVI(@POW(2.0,3.0))	; BUF  =  8

@REL()

Returns an integer 1 (memory space attribute N) if the assem-
bler is operating in relative mode, 0 otherwise.

Example:

IF	@REL()	; in relative mode?

@RND()

Returns a random value in the range 0.0 to 1.0.  The memory 
space attribute of the result will be None.

Example:

SEED	DC	@RND()	; save initial seed 
value

@RVB(<expr1>[,<expr2>])

Reverse the bits in <expr1> delimited by the number of bits 
in <expr2>. If <expr2> is omitted the field is bounded by the 
target word size. Both expressions must be single word integer 
values.

Example:

REV	EQU	@RVB(VAL)	; reverse all bits in 
value

@SCP(<str1>,<str2>)

Returns an integer 1 (memory space attribute N) if the two 
strings compare, 0 otherwise.  The two strings must be sepa-
rated by a comma.

Example:

IF	@SCP(STR,'MAIN')	; does STR equal MAIN?

@SGN(<expression>)

Returns the sign of <expression> as an integer:  -1 if the 
argument is negative, 0 if zero, 1 if positive.  The memory 
space attribute of the result will be None.  The <expression> 
may be relative or absolute.

Example:

IF	@SGN(INPUT)	; is sign positive?

@SIN(<expression>)

Returns the sine of <expression> as a floating point value.  
The memory space attribute of the result will be None.

Example:

DC	@SIN(@CVF(COUNT)*FREQ)	; compute sine val-
ue

@SNH(<expression>)

Returns the hyperbolic sine of <expression> as a floating 
point value.  The memory space attribute of the result will 
be None.

Example:

HSINE	EQU	@SNH(VAL)	; hyperbolic sine

@SQT(<expression>)

Returns the square root of <expression> as a floating point 
value.  <expression> must be positive.  The memory space at-
tribute of the result will be None.

Example:

SQRT	EQU	@SQT(3.5)	; SQRT  =  1.870829

@TAN(<expression>)

Returns the tangent of <expression> as a floating point value.  
The memory space attribute of the result will be None.

Example:

MOVE	#@TAN(1.0),D1.S	; load tangent

@TNH(<expression>)

Returns the hyperbolic tangent of <expression> as a floating 
point value.  The memory space attribute of the result will 
be None.

Example:

HTAN	=	@TNH(VAL)	; hyperbolic tangent

@UNF(<expression>)

Converts <expression> to a floating point value.  For frac-
tional DSPs (DSP56000) <expression> should represent a binary 
fraction.  

Example:

FRC	EQU	@UNF($400000)	; FRC  =  0.5

@XPN(<expression>)

Returns the exponential function (base e raised to the power 
of <expression>) as a floating point value.  The memory space 
attribute of the result will be None.

Example:

EXP	EQU	@XPN(1.0)	; EXP  =  2.718282


Chapter 4

SOFTWARE PROJECT MANAGEMENT

4.1	  INTRODUCTION

The Motorola DSP assemblers provide several directives designed to 
assist in the development of large software projects. Complex soft-
ware projects often are divided into smaller program units. These 
subprograms may be written by a team of programmers in parallel, 
or they may be programs written for a previous development effort 
that are going to be reused. The assembler provides directives to 
encapsulate program units and permit the free use of symbol names 
within subprograms without regard to symbol names used in other 
programs. These encapsulated program units are called sections. 
Sections are also the basis for relocating blocks of code and data, 
so that concerns about memory placement are postponed until after 
the assembly process.

4.2	  SECTIONS

A section is bounded by a SECTION directive and an ENDSEC direc-
tive.  For example:

SECTION  <section name>  [GLOBAL | STATIC | LOCAL]
	.
	.
Section source statements
	.
	.
ENDSEC

All symbols that are defined within a section have the <section 
name> associated with them.  This serves to protect them from like-
named symbols elsewhere in the program.  By default, a symbol de-
fined inside any given section is private to that section unless 
the GLOBAL or LOCAL qualifiers accompany the SECTION directive.  
More information on the GLOBAL and LOCAL qualifiers can be found 
in SECTIONS AND DATA HIDING, below.

Any code or data inside a section is considered an indivisible 
block with respect to relocation.  Code or data associated with a 
section is independently relocatable within the memory space to 
which it is bound, unless the STATIC qualifier follows the SECTION 
directive on the instruction line.  More information on the STATIC 
qualifier is available in SECTIONS AND RELOCATION, below.

4.3	  SECTIONS AND DATA HIDING

Symbols within a section are generally distinct from other symbols 
used elsewhere in the source program, even if the symbol name is 
the same.  This is true as long as the section name associated with 
each symbol is unique, the symbol is not declared public (XDEF or 
GLOBAL), and the GLOBAL or LOCAL qualifiers are not used in the 
section declaration (see below).  Symbols that are defined outside 
of a section are considered global symbols and have no explicit 
section name associated with them.  Global symbols may be refer-
enced freely from inside or outside of any section, as long as the 
global symbol name does not conflict with another symbol by the 
same name in a given section.  Consider the following example:

SYM1	EQU	1
SYM2	EQU	2

	SECTION	EXAMPLE

SYM1	EQU	3

	MOVE	#SYM1,R0
	MOVE	#SYM2,R1

	ENDSEC

	MOVE	#SYM1,R2

SYM1 and SYM2 are global symbols, initially defined outside of any 
section.  Then in section EXAMPLE another instance of SYM1 is de-
fined with a different value.  Because SYM1 was redefined inside 
the section, the value moved to R0 will be 3.  Since SYM2 is a 
global symbol the value moved to R1 will be 2.  The last move to 
R2 is outside of any section and thus the global instance of SYM1 
is used; the value moved to R2 is 1.

4.3.1	  Sections and Symbols

Symbols may be shared among sections through use of the XDEF and 
XREF directives.  The XDEF directive instructs the assembler  that 
certain symbol definitions that occur within the current section 
are to be accessible by other sections:

XDEF	<symbol>,<symbol>,...,<symbol>

The XREF directive instructs the assembler that all references to 
<symbol> within the current section are references to a symbol that 
was declared public within another section with the XDEF directive:

XREF	<symbol>,<symbol>,...,<symbol>

XDEFed symbols by default are recognized only in other sections 
which XREF them.  They can be made fully global (recognizable by 
sections which do not XREF them) by use of the XR option (see the 
OPT directive, Chapter 6).  Alternatively the GLOBAL directive (see 
Chapter 6) may be used within a section to make the named symbols 
visible outside of the section.  Both the XDEF and XREF directives 
must be used before the symbols to which they refer are defined or 
used in the section.  Here is another example:

SYM1	EQU	1
	SECTION	SECT1
	XDEF	SYM2
SYM1	EQU	2
SYM2	EQU	3
	ENDSEC
	SECTION	SECT2
	XREF	SYM2
	MOVE	#SYM1,R0
	MOVE	#SYM2,R1
	ENDSEC
	MOVE	#SYM2,R2

SYM1 is first defined outside of any section.  Then in section SECT1 
SYM2 is declared public with an XDEF directive.  SYM1 is also de-
fined locally to section SECT1.  In section SECT2 SYM2 is declared 
external via the XREF directive, followed by a move of SYM1 to R0.  
Since SYM1 was defined locally to section SECT1, the assembler uses 
the global value and moves a 1 to R0.  Because SYM2 was declared 
external in section SECT1 the value moved to R1 is 3.  If SYM2 had 
not been XREFed in section SECT2 the value moved to R1 would have 
been unknown at this point.  In the last instruction it is not known 
what value will be moved to R2 since SYM2 was not defined outside 
of any section or was not declared GLOBAL within a section.

If the GLOBAL qualifier follows the <section name> in the SECTION 
directive, then all symbols defined in the section until the next 
ENDSEC directive are considered global.  The effect is as if every 
symbol in the section were declared with the GLOBAL directive.  
This is useful when a section needs to be independently relocat-
able, but data hiding is not required.

If the LOCAL qualifier follows the <section name> in the SECTION 
directive, then all symbols defined in the section until the next 
ENDSEC directive are visible to the immediately enclosing section.  
The effect is as if every symbol in the section were defined within 
the parent section.  This is useful when a section needs to be in-
dependently relocatable, but data hiding within an enclosing sec-
tion is not required.

Symbols that are defined with the SET directive can be made visible 
with XDEF only in absolute mode, and the section name associated 
with the symbol will be the section name of the section where the 
symbol was first defined. This will be true even if the symbol value 
is changed in another section.

4.3.2	  Sections and Macros

The division of a program into sections controls not only labels 
and symbols, but also macros and DEFINE directive symbols.  Macros 
defined within a section are private to that section and are dis-
tinct from macros defined in other sections even if they have the 
same macro name.  Macros defined outside of sections are considered 
global and may be used within any section.  Similarly, DEFINE di-
rective symbols defined within a section are private to that sec-
tion and DEFINE directive symbols defined outside of any section 
are globally applied.  There are no directives that correspond to 
XDEF for macros or DEFINE symbols, therefore macros and DEFINE sym-
bols defined in a section can never be accessed globally.  If global 
accessibility is desired, the macros and DEFINE symbols should be 
defined outside of any section.  Here is an example:

	DEFINE	DEFVAL	'1'
	SECTION	SECT1
	DEFINE	DEFVAL	'2'
	MOVE	#DEFVAL,R0
	ENDSEC
	MOVE	#DEFVAL,R1

The second definition of DEFVAL is visible only inside SECT1, so 
the value moved to R0 will be 2.  However, the second move instruc-
tion is outside the scope of SECT1 and will therefore use the ini-
tial definition of DEFVAL.  This means that the value 1 will be 
moved to R1.

4.3.3	  Nested and Fragmented Sections

Sections can be nested to any level.  When the assembler encounters 
a nested section, the current section is stacked and the new sec-
tion is used.  When the ENDSEC directive of the nested section is 
encountered, the assembler restores the old section and uses it.  
The ENDSEC directive always applies to the most recent SECTION di-
rective.  Nesting sections provides a measure of scoping for symbol 
names, in that symbols defined within a given section are visible 
to other sections nested within it.  For example, if section B is 
nested inside section A, then a symbol defined in section A can be 
used in section B without XDEFing in section A or XREFing in section 
B.  This scoping behavior can be turned off and on with the NONS 
and NS options respectively (see the OPT directive, Chapter 6).

Sections may also be split into separate parts.  That is, <section 
name> can be used multiple times with SECTION and ENDSEC directive 
pairs.  If this occurs, then these separate (but identically named) 
sections can access each others symbols freely without the use of 
the XREF and XDEF directives.  If the XDEF and XREF directives are 
used within one section, they apply to all sections with the same 
section name.  The reuse of the section name is allowed to permit 
the program source to be arranged in an arbitrary manner (for ex-
ample, all statements that reserve X space storage locations 
grouped together), but retain the privacy of the symbols for each 
section.

4.4	  SECTIONS AND RELOCATION

When the assembler operates in relative mode (the default), sec-
tions act as the basic grouping for relocation of code and data 
blocks.  For every section defined in the source a set of location 
counters is allocated for each DSP memory space.  These counters 
are used to maintain offsets of data and instructions relative to 
the beginning of the section.  At link time sections can be relo-
cated to an absolute address, loaded in a particular order, or 
linked contiguously as specified by the programmer.  Sections which 
are split into parts or among files are logically recombined so 
that each section can be relocated as a unit.

Sections may be relocatable or absolute.  In the assembler absolute 
mode (command line -A option) all sections are considered absolute.  
In relative mode, all sections are initially relocatable.  However, 
a section or a part of a section may be made absolute either im-
plicitly by using the ORG directive, or explicitly through use of 
the MODE directive.

If the assembler encounters an ORG directive with an absolute runt-
ime address specification it switches to absolute mode and begins 
generating absolute addresses within the enclosing section.  Note 
that the mode change is effective only if  the assembler was started 
in relative mode; if the -A command line option is used the assem-
bler always generates absolute addresses.  The assembler continues 
to generate absolute code until an ENDSEC directive is encountered, 
or the mode is explicitly changed via the MODE directive.

The MODE directive allows for arbitrary switching between absolute 
and relocatable code generation:

MODE	<ABS[OLUTE] | REL[ATIVE]>

The MODE directive may be issued at any time in the assembly source 
to alter the set of location counters used for section addressing.  
Code generated while in absolute mode will be placed in memory at 
the location determined during assembly.  Relocatable code and data 
within a section are combined at link time, even if absolute blocks 
are interspersed among relocatable blocks.  The MODE directive has 
no effect when the command line -A option is active.  The following 
is an example:

	SECTION	EXAMPLE	; relocatable section

; code/data generated here is relocatable

	MODE	ABSOLUTE

; code/data generated here is absolute; it will be
; placed in memory at the location specified during
; assembly

	MODE	REL

; back to relocatable; code/data generated here
; will be combined with the previous relocatable block,
; as long as memory space and mappings are compatible

	ORG	P:$200

; code/data generated here will be absolute
; until ENDSEC directive is found

	ENDSEC

More information on the ORG and MODE directives can be found in 
ADDRESS ASSIGNMENT and under the individual directive descriptions 
in Chapter 6.

If the STATIC qualifier follows the <section name> in the SECTION 
directive, then all code and data defined in the section until the 
next ENDSEC directive are relocated in terms of       the immedi-
ately enclosing section. The effect with respect to relocation is 
as if all code and data in the section were defined within the par-
ent section. This is useful when a section needs data hiding, but 
independent relocation is not required.

4.5	  ADDRESS ASSIGNMENT

The Motorola DSP assembler can support absolute address assignment 
at assembly time or generation of relocatable program addresses 
which are resolved during the linking phase.  The ORG directive is 
used to specify memory space changes, mappings to physical memory, 
and absolute address assignment.

Various memory layouts require special handling for data generation 
or location counter updating. In the case of L memory, two words 
of code or data are produced for each increment of the location 
counter. There are many kinds of E memory depending on the charac-
teristics of the RAM devices used. In most cases E memory implies 
splitting the generated word into 8-bit triplets or 8 and 16-bit 
pairs on output, and adjusting the location counter appropriately.

The assembler allows for two sets of program counters per memory 
space, a set of load counters and a set of runtime counters. The 
distinction between load and runtime counters is maintained so that 
the assembler can support overlays, or runtime transfers of code/
data from one memory space to another. In these cases code or data 
might be loaded in one memory space at a given address, but then 
copied to a different memory space and address for execution. The 
assembler can produce output for either absolute or relocatable 
overlays.

Motorola DSPs are capable of performing special-purpose addressing 
on data structures suited to digital signal processing applica-
tions.  Two such data structures are the modulo buffer and the re-
verse-carry buffer, collectively referred to as circular buffers.  
Due to the way they are accessed and manipulated, these buffers 
generally are constrained to a particular size or starting address.  
The assembler provides directives for aligning buffer base address-
es, allocating buffer space, and initializing buffer contents.

4.5.1	  The ORG Directive

The ORG directive specifies which memory space will be the runtime 
memory space and which counter (the H, L, default, or numbered 
runtime counter associated with that memory space and section) will 
be the runtime location counter.  At the same time, the ORG direc-
tive indicates which memory space will be the load memory space and 
which counter (the H, L, default, or numbered load counter associ-
ated with that memory space and section)  will be used as the load 
location counter.  In addition, the ORG directive can be used to 
specify a physical mapping to DSP memory and to assign initial val-
ues to the runtime and load location counters.

The names of the counters (High, Low, and default) are symbolic 
only, and the assembler performs no checks to insure that the value 
assigned to the High counter is greater than the Low.  Moreover, 
there is no inherent relationship among numbered counters, except 
that counters 0, 1, and 2 correspond to the default, Low, and High 
counters, respectively.  Counters are useful for providing mnemonic 
links between runtime and load memory spaces or among individual 
memory blocks.  Separate counters can be used to obtain blocks 
within a common section which are accessed from one memory space 
but mapped to separate physical memories.  Also counters are nec-
essary for handling relocatable overlays at link time, as the DSP 
linker does not support the notion of separate load and runtime 
counters.  See the examples below for more information on location 
counter usage.

The ORG directive is organized as follows:

        ORG 
<rms>[<rlc>][<rmp>]:[<exp1>][,<lms>[<llc>][<lmp>]:[<exp2>]]

or alternatively:

        ORG 
<rms>[<rmp>][(<rce>)]:[<exp1>][,<lms>[<lmp>][(<lce>)]:[<exp2
>]]

<rms>

Which memory space (X, Y, L, P, or E) will be used as the 
runtime memory space. If the memory space is L, any al-
located datum with a value greater than the target word 
size will be extended to two words; otherwise, it is 
truncated. If the memory space is E, then depending on 
the memory space qualifier, any generated words will be 
split into bytes, one byte per word, or a 16/8-bit com-
bination.

<rlc>

Which runtime counter H, L, or default (if neither H or 
L is specified), that is associated with the <rms> will 
be used as the runtime location counter.

<rmp>

Indicates the runtime physical mapping to DSP memory:  I 
- internal, E - external, R - ROM, A - port A, B - port 
B.  If not present, no explicit mapping is done.

<rce>

Non-negative absolute integer expression representing 
the counter number to be used as the runtime location 
counter.  Must be enclosed in parentheses.  Should not 
exceed the value 65535.

<exp1>

Initial value to assign to the runtime counter used as 
the <rlc>.  If <exp1>  is a relative expression the as-
sembler uses the relative location counter.  If <exp1>  
is an absolute expression the assembler uses the absolute  
location counter.  If <exp1> is not specified, then the 
last value and mode that the counter had will be used.

<lms>

Which memory space (X, Y, L, P, or E) will be used as the 
load memory space. If the memory space is L, any allo-
cated datum with a value greater than the target word 
size will be extended to two words; otherwise, it is 
truncated. If the memory space is E, then depending on 
the memory space qualifier, any generated words will be 
split into bytes, one byte per word, or a 16/8-bit com-
bination.

<llc>

Which load counter, H, L, or default (if neither H or L 
is specified), that is associated with the <lms> will be 
used as the load location counter.

<lmp>

Indicates the load physical mapping to DSP memory:  I - 
internal, E - external, R - ROM, A - port A, B - port B.  
If not present, no explicit mapping is done.

<lce>

Non-negative absolute integer expression representing 
the counter number to be used as the load location 
counter.  Must be enclosed in parentheses.  Should not 
exceed the value 65535.

<exp2>

Initial value to assign to the load counter used as the 
<llc>.  If <exp2>  is a relative expression the assembler 
uses the relative location counter.  If <exp2>  is an 
absolute expression the assembler uses the absolute  lo-
cation counter.  If <exp2> is not specified, then the 
last value and mode that the counter had will be used.

The ORG directive is useful in multi-programmer projects because 
it provides a means for the individual programmer to specify in 
which memory space and which segment of that memory space the code 
being written will be located without specifying an absolute ad-
dress. Absolute address assignment can be deferred until the var-
ious components of the program are brought together. The utility 
of the ORG directive is not limited to multi-programmer projects. 
Even in single programmer projects, the ORG directive supports ma-
nipulation of overlays and the intermixing of label definition and 
code generation in multiple memory spaces without having to rein-
itialize a location counter every time the load memory space is 
changed.

4.5.2	  Overlays

If the last half of the operand field in an ORG directive dealing 
with the load memory space and counter is not specified, then the 
assembler will assume that the load memory space and load location 
counter are the same as the runtime memory space and runtime loca-
tion counter.  In this case, object code is being assembled to be 
loaded into the address and memory space where it will be when the 
program is run, and is not an overlay.

If the load memory space and counter are given in the operand field, 
then the assembler always generates code for an overlay. Whether 
the overlay is absolute or relocatable depends upon the current 
operating mode of the assembler and whether the load counter value 
is an absolute or relative expression. If the assembler is running 
in absolute mode, or if the load counter expression is absolute, 
then the overlay is absolute. If the assembler is in relative mode 
and the load counter expression is relative, the overlay is relo-
catable. Runtime relocatable overlay code is addressed relative to 
the location given in the runtime location counter expression. This 
expression, if relative, may not refer to another overlay block. 
See section 1.6 for more information on location counters and over-
lays.

The values and memory space attributes of both the load and runtime 
location counters can be accessed with the @LCV function (see Sec-
tion 3.8). This is particularly useful when assigning the load lo-
cation counter value to a label as a reference point for the overlay 
manager part of the program. The High, Low, default, or numbered 
counter assignment can be determined by using the @CTR function 
(Section 3.8).

4.5.3	  Address Assignment Examples

Some examples of the ORG directive are as follows:

ORG  P:$1000

Sets the  runtime memory space to P.  Selects the default runt-
ime counter (counter 0) associated with P space to use as the 
runtime location counter and initializes it to $1000.  The 
load memory space is implied to be P, and the load location 
counter is assumed to be the same as the runtime location 
counter.

ORG  PHE:

Sets the runtime memory space to P.  Selects the H load counter 
(counter 2) associated with P space to use as the runtime lo-
cation counter.  The H counter will not be initialized, and 
its last value will be used.  Code generated hereafter will 
be mapped to external (E) memory.  The load memory space is 
implied  to be P, and the load location counter is assumed to 
be the same as the runtime location counter.

ORG  PI:OVL1,Y:

Indicates code will be generated for an overlay. The runtime 
memory space is P, and the default counter is used as the runt-
ime location counter. It will be reset to the value of OVL1. 
If the assembler is in absolute mode via the -A command line 
option then OVL1 must be an absolute expression. If OVL1 is 
an absolute expression the assembler uses the absolute runtime 
location counter. If OVL1 is a relocatable value the assembler 
uses the relative runtime location counter. In this case OVL1 
must not itself be an overlay symbol (e.g. defined within an 
overlay block). The load memory space is Y. Since neither H, 
L, nor any counter expression was specified as the load 
counter, the default load counter (counter 0) will be used as 
the load location counter. The counter value and mode will be 
whatever it was the last time it was referenced.

ORG  XL:,E8:

Sets the runtime memory space to X.  Selects the L counter 
(counter 1) associated with X space to use as the runtime lo-
cation counter.  The L counter will not be initialized, and 
its last value will be used.  The load memory space is set to 
E, and the qualifier 8 indicates a bytewise RAM configuration. 
Instructions and data will be generated eight bits per output 
word with byte-oriented load addresses. The default load 
counter will be used and there is no explicit load origin.

ORG  P(5):,Y:$8000

Indicates code will be generated for an absolute overlay.  The 
runtime memory space is P, and the counter used as the runtime 
location counter is counter 5.  It will not be initialized, 
and the last previous value of counter 5 will be used.  The 
load memory space is Y.  Since neither H, L, nor any counter 
expression was specified as the load counter, the default load 
counter (counter 0) will be used as the load location counter.  
The default load counter will be initialized to $8000.

If the last example shown was used in the following code sequence 
(assume the runtime counter associated with P space had a previous 
value of $0010),

	ORG	P(5):,Y:$8000
RLMUL	MOVE	X:(R0),D4.S	Y:(R4),D7.S
	FMPY.S	D4,D7,D0
	MOVE	D0.S,X:(R1)

then the label RLMUL would have a value of $0010 and a memory space 
attribute of P space; the code generated would load into Y memory 
starting at $8000; and the runtime address associated with the code 
would start at $0010.

4.5.4	  Circular Buffers

To take advantage of the special DSP addressing capabilities a cir-
cular buffer must be aligned on an appropriate address boundary 
with respect to its size.  For a buffer to be located properly in 
memory the lower bits of the starting address which encompass one 
less than the buffer size must be zero.  For example, the lowest 
address greater than zero at which a buffer of size 32 may be lo-
cated is 32 (20 hexadecimal).  More generally, the buffer base ad-
dress must be modulo the buffer size, or a multiple of 2k, where 
2k is greater than or equal to the size of the buffer.

Buffers may be allocated manually or by using one of the assem-
bler's special buffer directives:

	ORG	X:$100
BUF1	DS	24
BUF2	DSM	32

The ORG statement sets the origin to hexadecimal 100 in X memory.  
The first buffer BUF1 is manually allocated with a size of 24.  
Since the starting address is hex 100 the buffer is already suit-
ably aligned.  The label BUF1 is assigned the runtime counter value 
at the beginning of the buffer.  The second buffer is allocated 
using the DSM directive, which automatically sets the buffer start-
ing address before reserving space.  In this case, the first buffer 
ended at location 117 hexadecimal, so the assembler advances the 
program counter to location 120 hex before assigning a value to the 
buffer label BUF2.

Buffers are special-purpose data structures, but they are named and 
accessed with labels like any other data block. They therefore ad-
here to the same rules governing data hiding in sections that any 
other segment of code or data would follow. A buffer allocated when 
the assembler is in absolute mode (either via -A or an absolute ORG 
or MODE directive) is placed in memory according to the absolute 
value of the runtime location counter at assembly time. A buffer 
allocated in relative mode (a relocatable buffer) is suitably 
aligned within its relocation section at assembly time. During the 
link phase a section enclosing any relocatable buffers is located 
based on the largest relocatable buffer it contains, unless the 
buffers inside the section are auto-aligned. This insures that any 
smaller buffers within the section are properly aligned. If any 
buffers in the section are auto-aligned, they will be relocated 
independent of any other code or data in the section. Note that 
repositioning of any buffer, whether relocatable or absolute, may 
result in alignment gaps in memory depending on the layout of data 
surrounding the buffer blocks.

4.6	  EXAMPLE 1: MULTI-PROGRAMMER ENVIRONMENT 

Typical multi-programmer projects are often split into tasks rep-
resenting functional units. For discussion purposes, suppose a 
project has been divided into three tasks - I/O, FILTER, and MAIN. 
Each task will be written by a separate programmer as a separate 
section. For example, when the I/O task has been written, there 
will be a file called IO.ASM. This file will have the following 
form:

	SECTION I_O
	XREF I_PORT,O_PORT
	ORG  XL:
	.
	.
	<storage location definitions>
	.
	.
	ORG  P:
	.
	.
	<IO section source statements>
	.
	.
	ENDSEC

In this example, because the X space storage locations were defined 
within the section I_O, they will be private storage locations that 
are accessible only by the I_O handler, and cannot be referenced 
by other sections.  If global memory resource management is de-
sired, then the I_O section would not have defined any storage lo-
cations, and these would have been defined as XREF.  The X space 
data will be addressed through the Low runtime counter.  The P mem-
ory code is also private to the I_O section and uses the default 
runtime location counter for address generation.

In the discussion below, assume that the programmers responsible 
for the FILTER and MAIN sections have similar program structures 
located in files named FILTER.ASM and MAIN.ASM respectively.  The 
program units can be combined either by invoking a final assembly 
step to assign absolute addresses, or by assembling the modules 
separately and then linking.

4.6.1	  Absolute Mode Implementation

To assemble the entire project source code, a new file called 
PROJECT.ASM would be created and would have the form:

	ORG  XLE:$0000
	.
	<global low memory X storage declarations (if any)>
	.
	ORG  YLE:$0000
	.
	<global low memory Y storage declarations (if any)>
	.
	ORG  YH:$FFC0
	.
	<global high memory Y storage declarations (if any)>
	.
	ORG  XH:$FFC0
	.
	<global high memory X storage declarations (if any)>
	.
	; initialize internal low Program memory location 
counter
	ORG  PL:$1000
	; initialize external high Program memory location 
counter
	ORG  PHE:$F000
	INCLUDE 'MAIN.ASM'
	INCLUDE 'IO.ASM'
	INCLUDE 'FILTER.ASM'
	END  ENTRY

This file provides the project manager with a mechanism to organize 
memory utilization to suit the application. For example, the ex-
ternal high P memory initialization statement might correspond to 
the memory location of an external EPROM.

After the location counters corresponding to the X, Y, and P(ro-
gram) memory spaces are initialized, the assembler is directed to 
take input from the MAIN.ASM file with the INCLUDE directive. With-
in the MAIN.ASM file, the source statements are assembled and ob-
ject code is generated. The X, Y, L, and P(rogram) location 
counters (High, Low) are advanced corresponding to the number of 
words generated for each memory space and location counter in use.

When the end of the MAIN.ASM file is encountered, the assembler 
returns to the next sequential statement in the PROJECT.ASM file. 
This directs the assembler to start taking input from the IO.ASM 
file. Within this file, the ORG PL: statement directs the assembler 
to set the current memory space to P(rogram) and restore the last 
used P(rogram) L(ow) location counter. The <IO source program 
statements> shown previously will be assembled at the next avail-
able Low Program memory space. When the end of the IO.ASM file is 
encountered, the X, Y, and P(rogram) location counters (High and 
Low) will have been advanced corresponding to the number of words 
generated for each memory space.

In a similar manner, the file FILTER.ASM will be assembled. The 
last statement of the PROJECT.ASM file informs the assembler that 
this is the last logical source statement, and the starting address 
for the object module will be a label called ENTRY. In the example 
above, ENTRY would have been a label defined in the section MAIN 
and declared as global with the XDEF directive.

4.6.2	  Relative Mode Implementation

Using the assembler default relative mode, each of the source files 
is assembled separately. For each section defined in the input 
files a separate set of location counters is maintained such that 
all memory spaces for each section begin at relative address zero. 
The linker is invoked to combine the files and establish base ad-
dresses:

DSPLNK  -B  -M  -OXLI:0  -OYLI:0  -OYH:FFC0  -OXH:FFC0  \
	-OPL:1000  -OPHE:A000  MAIN  IO  FILTER

The linker reads the command input and sets up base values for all 
counters specified on the command line. In this example, the X and 
Y low memory counters are initialized to zero, whereas the X and Y 
high memory counters are set to FFC0 hexadecimal. The program low 
and high memory counters are initialized similarly. When the linker 
creates the executable file it reads the input files and sets the 
starting address for all sections relative to the values obtained 
from the command line. As the MAIN object file is read the linker 
increments the section counters for all appropriate memory spaces.

After the MAIN object file is processed, the IO object file is read. 
The section named I_O contained an ORG directive indicating a 
switch to the low X data memory counter. Recall that the assembler 
generated relocatable code for the I_O section source such that the 
low X data memory counter begins at zero. The linker adjusts the 
low X memory counter associated with section I_O to reflect any 
previous data generation performed in low X memory (e.g. in MAIN). 
The FILTER module is linked in a similar fashion.

Another way for specifying base addresses, instead of lengthy com-
mand line options, is through a memory control file. The memory 
control file allows the programmer to indicate memory space start-
ing addresses analogously to the command line approach. In addi-
tion, the memory control file offers finer control over placement 
of sections in memory. See the Motorola DSP Linker/Librarian Ref-
erence Manual for more information on the memory control file.

The preceding examples described two methods for organizing a soft-
ware project. Refer to the descriptions of the ORG and SECTION di-
rectives in Chapter 6 for a more detailed discussion. See also the 
Motorola DSP Linker/Librarian Reference Manual for more informa-
tion on relocation and linking. One other assembler directive that 
should be mentioned (although not shown in the previous example) 
is the MACLIB directive which allows sections to share a common 
macro library. The MACLIB directive is discussed more fully in 
Chapter 5.

4.7	  EXAMPLE 2: OVERLAYS

An overlay is a transfer of code or data from one memory space or 
address to another memory space or address at runtime.  Often the 
transfer involves copying different blocks of code or data over a 
common storage area as runtime circumstances dictate; hence the 
name overlay.  Overlays are useful for moving code into internal 
program memory from an external memory source such as EPROM.  They 
are also effective when implementing large programs with multiple 
segments which do not need to be accessed concurrently.  Consider 
the following program fragment contained in a file called 
OVER1.ASM:

	SECTION	OVERLAY1
	XREF	OVLBASE
	XDEF	OVL1,O1SIZE
	ORG	X:
OVL1
	ORG	P:OVLBASE,X:
START
	.
	.
	<overlay source statements>
	.
	.
END
O1SIZE	EQU	END-START
	ENDSEC

This is a sample of overlay code bounded by a SECTION directive. 
The overlay base, or the place to which this block of code will be 
moved for execution, is declared external at OVLBASE (OVLBASE is 
actually defined elsewhere). The label OVL1 is XDEFed to provide a 
handle for moving the block at runtime, and O1SIZE is also XDEFed 
so that the overlay management code knows how many words to move. 
Note that the OVL1 label is placed before the ORG for the overlay 
so that it remains a valid address in X memory during execution. 
The overlay ORG directive insures that subsequent addresses will 
be based from OVLBASE at runtime. The size of the overlay block 
(O1SIZE) is computed by subtracting the START label value from the 
END label address. Assume for purposes of discussion that there are 
other files containing similar overlay code with names OVER2.ASM 
and OVER3.ASM.

4.7.1	  Absolute Mode Implementation

In order to avoid binding addresses within the individual overlay 
modules, the programmer could devise a preamble file called OVL-
PROJ.ASM which sets the appropriate counters and establishes the 
overlay base address.  Note that the following code assumes a 
DSP96000, but similar instructions would apply for other target 
processors:

	SECTION	OVLPROJECT
	XDEF	OVLBASE
	XREF	OVL1,O1SIZE
	XREF	OVL2,O2SIZE
	XREF	OVL3,O3SIZE
	ORG	XE:$100			; set absolute base for overlay 
sections
	ORG	PI:$200			; set absolute base address for 
overlay
OVLBASE	DS	$400			; reserve space for overlay 
area
MOVEOV1					; code to move first overlay 
segment
	MOVE	#OVL1,R0			; load overlay code address
	MOVE	#OVLBASE,R1			; load overlay base address
	MOVE	#O1SIZE,D1.M			; load overlay code size
	DO	D1.M,_ENDLOOP			; loop to move data words into 
P memory
	MOVE	X:(R0)+,D0.M			; get word of overlay from data 
memory
	MOVE	D0.M,P:(R1)+			; store word of overlay into P 
memory
_ENDLOOP
	.
	.
	.
	ENDSEC

The overlay base address OVLBASE is made global with the XDEF 
statement.  The overlay segments and their sizes are made visible 
to the project section by using the XREF directive.  The first ORG 
establishes where the overlay segments will be placed in memory 
contiguously at load time.  The second ORG sets up the absolute 
base address for the overlay area common to all of the overlay seg-
ments.  Uninitialized space is allocated for the overlay area, im-
mediately followed by code to move the overlay segments into the 
common area at runtime.  The following assembler command line will 
process the header file and all overlay segments:

ASM96000 -A -B -L OVLPROJ OVER1 OVER2 OVER3 START

The assembler is invoked in absolute mode (-A option), and gener-
ates an executable and listing file.  All files on the command line 
are processed as a single assembly run and all are used to produce 
the output.  OVLPROJ.ASM is read first and sets up the appropriate 
absolute addresses for later sections.  Then each overlay file is 
read and loaded one after the other at external X memory address 
100 hexadecimal.  However, since each overlay module was intended 
to run starting at OVLBASE in P memory, all labels and jumps to 
those labels within the overlay code will be relative to the over-
lay base address.  This means that the code in each of the overlay 
modules, when loaded by the overlay management code in the OVL-
PROJECT section, will start executing at internal P memory address 
200 hexadecimal.  The file START.ASM contains an END directive 
which indicates the program start address after loading.

4.7.2	  Relative Mode Implementation

In relative mode each of the overlay files is assembled separately 
to create individual object files. The object files are combined 
to build a single executable file. A preamble file OVLPROJ.ASM con-
taining overlay management code might appear as follows. Note that 
this code assumes a DSP96000, but similar instructions would apply 
for other target processors:

	SECTION	OVLPROJECT
	XDEF	OVLBASE
	XREF	OVL1,O1SIZE
	XREF	OVL2,O2SIZE
	XREF	OVL3,O3SIZE
	ORG	PI:	; set base address for overlay
MOVEOV1			; code to move first overlay 
segment
	MOVE	#OVL1,R0	; load overlay code address
	MOVE	#OVLBASE,R1	; load overlay base address
	MOVE	#O1SIZE,D1.M	; load overlay code size
	DO	D1.M,_ENDLOOP	; loop to move data words into 
P memory
	MOVE	X:(R0)+,D0.M	; get word of overlay from data 
memory
	MOVE	D0.M,P:(R1)+	; store one word of overlay 
into P memory
_ENDLOOP
	.
	.
	.
OVLBASE	DS	$400	; reserve space for overlay 
area
	ENDSEC

Note that the ORG to P space does not specify an absolute address. 
In order to obtain the same result from these files as in an abso-
lute mode implementation the following linker command line would 
be used:

DSPLNK  -B  -M  -OXE:100  -OPI:200  OVLPROJ  OVER1  OVER2  OVER3

The linker scans the command line and sets the base addresses for 
X and P memory. Here the X default counter is set to hex 100 and 
mapped to external memory; likewise the P default counter is set 
to hex 200 and mapped to internal memory. Base addresses can also 
be established with the linker memory control file.

The linker reads each input object file, placing the header file 
in internal P memory and combining the overlay modules into a con-
tiguous block loaded into external X memory at location 100 hexa-
decimal. Any labels or jumps within the overlay blocks are resolved 
to addresses relative to the relocatable symbol OVLBASE. Since OV-
LBASE is the first load P memory address it is assigned the value 
200 hexadecimal. The linker does not guarantee that a given symbol 
or section will begin at a particular location unless that infor-
mation is explicitly specified in the linker memory control file. 
For more information on specific linker operations see the Motorola 
DSP Linker/Librarian Reference Manual.

4.8	  EXAMPLE 3: BOOTSTRAP OVERLAY

Many Motorola DSP processors, specifically those with RAM-based 
program memory, support a bootstrap mode of operation. This in-
volves mapping a built-in ROM-based bootstrap program into P mem-
ory, executing the program to move user-supplied code from another 
location (usually EPROM) into program RAM, then transferring con-
trol to the user program. Because the user program is loaded in one 
location (e.g. EPROM) but moved to another for execution, it is a 
natural application for assembly language overlay semantics. An-
other wrinkle in bootstrap mode is that user instruction words are 
loaded in bytewise fashion, such that the load location counter 
must be incremented by bytes rather than words. Consider the fol-
lowing section fragments contained in two files called SECT1.ASM 
and SECT2.ASM respectively:

	SECTION	SECT1
	ORG	PI(1):,PE(2)
START1
	.
	.
	<source statements>
	.
	.
END1
	ENDSEC

	. . .

	SECTION	SECT2
	ORG	PI(1):,PE(2)
START2
	.
	.
	<source statements>
	.
	.
END2
	ENDSEC

4.8.1	  Absolute Mode Implementation

In order to avoid binding addresses within the individual modules, 
the programmer could devise a preamble file called BOOTPROJ.ASM 
which sets the appropriate options and establishes load and runtime 
base addresses:

	OPT	LB		; increment load counter 
by bytes
	ORG	PI(1):$100,PE(2):$C000		; set runtime RAM ad-
dress,
				; bytewide load ROM ad-
dress

The OPT directive with the LB option indicates that the assembler 
should increment the load counter by the number of bytes in the 
target processor word. This guarantees that the EPROM addresses 
will be correct for bytewide loading during bootstrap processing. 
In the ORG directive, the runtime location counter, tagged as 1 and 
mapped to internal memory, is set to hex 100. The load counter is 
tagged as 2, mapped to external memory, and set to hex C000, where 
the built-in bootstrap program will begin loading bytes after pro-
cessor reset. The files are assembled using the command below:

ASM56000  -A  -B  -L  BOOTPROJ   SECT1  SECT2

The assembler is invoked in absolute mode (-A option), and gener-
ates an executable and listing file. All files on the command line 
are processed as a single assembly run and all are used to produce 
the output. BOOTPROJ.ASM is read first and sets up the appropriate 
absolute addresses for later sections. Since no explicit base ad-
dress was given in the section files, both load and runtime ad-
dresses will continue from one section to the other, e.g. they will 
be contiguous. For example, if only two words of instruction were 
between each of the START and END labels, the runtime value for 
END1 and START2 would be hex 102. However, the load address of the 
code associated with these labels, assuming a 16 bit target word 
size, would be C004 hexadecimal. Similarly, the runtime value for 
END2 would be 104 hex and the corresponding load address would be 
C008 hexadecimal.

4.8.2	  Relative Mode Implementation

In relative mode each of the source files is assembled separately 
to create individual object files. The object files are combined 
to build a single executable file. A preamble file is not necessary 
to handle bootstrap files in relative mode because the addresses 
are established at link time. In order to generate bytewide load 
addresses the LB option can be specified on the assembler command 
line using the -O command line option:

ASM56000  -B  -L  -OLB  SECT1

This command assembles the file SECT1.ASM and creates a relocatable 
object file called SECT1.CLN. The listing file shows that the 
starting address of the section is zero; however, because of the 
LB option on the command line the load counter will increment at 
twice the rate of the runtime counter (assuming a 16 bit DSP56100 
family target processor). A similar command is used to assemble the 
SECT2 module. The two files are linked as follows:

DSPLNK  -BBOOTPROJ.CLD  "-OPI(1):100"  "-OPE(2):C000"  SECT1  
SECT2

The linker scans the command line and sets the base addresses for 
P internal and external memory. The quotes around the -O options 
are necessary to avoid interpretation of parentheses by some host 
command interpreters. Here the P counter number 1 is set to hex 100 
and mapped to internal memory; likewise the P counter number 2 is 
set to hex C000 and mapped to external memory. Base addresses can 
also be established with the linker memory control file. Since no 
explicit overlay base addresses were encountered in the source 
files, both load and runtime addresses for the sections will be 
adjacent and non-overlapping. Assuming a code size of 2 for each 
section and a 16 bit word size, the value for label START1 will be 
hex 100 and the value for START2 will be hex 102; the corresponding 
load addresses will be C000 hex and C004 hex, respectively. The 
executable output will be written to the file BOOTPROJ.CLD.


Chapter 5

MACRO OPERATIONS AND CONDITIONAL ASSEMBLY

5.1	  MACRO OPERATIONS

Programming applications frequently involve the coding of a repeat-
ed pattern or group of instructions.  Some patterns contain vari-
able entries which change for each repetition of the pattern.  
Others are subject to conditional assembly for a given occurrence 
of the instruction group.  In either case, macros provide a short-
hand notation for handling these instruction patterns.  Having de-
termined the iterated pattern, the programmer can, within the 
macro, designate selected fields of any statement as variable.  
Thereafter by invoking a macro the programmer can use the entire 
pattern as many times as needed, substituting different parameters 
for the designated variable portions of the statements.

When the pattern is defined it is given a name.  This name becomes 
the mnemonic by which the macro is subsequently invoked  (called).  
If the name of the macro is the same as an existing assembler di-
rective or mnemonic opcode, the macro will replace the directive 
or mnemonic opcode, and a warning will be issued.  The warning can 
be avoided by the use of the RDIRECT directive, which is used to 
remove entries from the assembler's directive and mnemonic tables.  
If directives or mnemonics are removed from the assembler's tables, 
then no warning will be issued when the assembler processes macros 
whose names are the same as the removed directive or mnemonic en-
tries.  However, if a macro is defined through the MACLIB directive 
which has the same name as an existing directive or opcode, it will 
not automatically replace that directive or opcode as previously 
described.  In this case, the RDIRECT directive must be used to 
force the replacement.  See the description of the MACLIB directive 
below.

The macro call causes source statements to be generated.  The gen-
erated statements may contain substitutable arguments.  The state-
ments produced by a macro call are relatively unrestricted as to 
type.  They can be any processor instruction, almost any assembler 
directive, or any previously-defined macro.  Source statements re-
sulting from a macro call are subject to the same conditions and 
restrictions that are applied to statements written by the program-
mer.

To invoke a macro, the macro name must appear in the operation code 
field of a source statement.  Any arguments are placed in the op-
erand field.  By suitably selecting the arguments in relation to 
their use as indicated by the macro definition, the programmer 
causes the assembler to produce in-line coding variations of the 
macro definition.

The effect of a macro call is to produce in-line code to perform a 
predefined function.  The code is inserted in the normal flow of 
the program so that the generated instructions are executed with 
the rest of the program each time the macro is called.

An important feature in defining a macro is the use of macro calls 
within the macro definition.  The assembler processes such nested 
macro calls at expansion time only.  The nesting of one macro def-
inition within another definition is permitted.  However, the nest-
ed macro definition will not be processed until the primary macro 
is expanded.  The macro must be defined before its appearance in a 
source statement operation field.

5.2	  MACRO LIBRARIES

The Motorola DSP assembler allows for the maintenance of macro li-
braries with the MACLIB directive.  This directive is used to spec-
ify the pathname (as defined by the host operating system) of a 
directory that contains macro definitions.  Each macro definition 
must be in a separate file, and the file must be named the same as 
the macro with the extension .ASM added.  For example, BLOCKMV.ASM 
would be a file that contained the definition of the macro called 
BLOCKMV.

If a MACLIB directive has been specified in the source code and the 
assembler encounters a name in the operation field that is not a 
previously defined macro or is not contained in the directive or 
mnemonic tables, the directory specified in the MACLIB directive 
will be searched for a file of that name (with the .ASM extension 
added).  If such a file is found, the current source line will be 
saved, and the file will be opened for input as an INCLUDE file.  
When the end of the file is encountered, the source line is restored 
and processing is resumed.

Because the source line is restored, the processed file must have 
a macro definition of the unknown name, or an error will result 
when the source line is restored and processed.  However, the pro-
cessed file is not limited to macro definitions, and can include 
any legal source code statements.  Multiple MACLIB directives may 
be given, in which case the assembler will search each directory 
in the order in which they were specified.

5.3	  MACRO DEFINITION

The definition of a macro consists of three parts: the header, 
which assigns a name to the macro and defines the dummy arguments; 
the body, which consists of prototype or skeleton source state-
ments; and the terminator.  The header is the MACRO directive, its 
label, and the dummy argument list.  The body contains the pattern 
of standard source statements.  The terminator is the ENDM direc-
tive.

The header of a macro definition has the form:

<label>	MACRO	[<dummy argument list>]		[<comment>]

The required label is the symbol by which the macro will be called.  
The dummy argument list has the form:

[<dumarg>[,<dumarg>,...,<dumarg>]]

The dummy arguments are symbolic names that the macro processor 
will replace with arguments when the macro is expanded (called).  
Each dummy argument must obey the same rules as global symbol 
names.  Dummy argument names that are preceded by an underscore are 
not allowed.  Dummy arguments are separated by commas.

For example, consider the following macro definition:

N_R_MUL	MACRO	NMUL,AVEC,BVEC,RESULT			header
;
;This macro implements N real multiplies
;RESULT(I) = AVEC(I) * BVEC(I) I=1..NMUL
;where
;	NMUL	= number of multiplications
;	AVEC	= base address of array AVEC(I)
;	BVEC	= base address of array BVEC(I)
;	RESULT	= base address of array RESULT(I)
;
	MOVE	#AVEC,R0			body
	MOVE	#BVEC,R4
	MOVE	#RESULT,R1
	MOVE	X:(R0)+,D4.S	Y:(R4)+,D7.S
	DO	#NMUL,_ENDLOOP
	FMPY.S	D4,D7,D0	X:(R0)+,D4.S			
Y:(R4)+,D7.S
	MOVE	D0.S,X:(R1)+
_ENDLOOP
	ENDM				terminator

When a macro call is executed, the dummy arguments within the macro 
definition (NMUL,AVEC,BVEC,RESULT in the example above) are re-
placed with the corresponding argument as defined by the macro 
call.

All local labels within a macro are considered distinct for the 
currently active level of macro expansion (unless the macro local 
label override is used, see below).  These local labels are valid 
for the entire macro expansion and are not considered bounded by 
non-local labels.  Therefore, all local labels within a macro must 
be unique.  This mechanism allows the programmer to freely use lo-
cal labels within a macro definition without regard to the number 
of times that the macro is expanded.  Non-local labels within a 
macro expansion are considered to be normal labels and thus cannot 
occur more than once unless used with the SET directive (see Chap-
ter 6).

When specifying a local label within the body of a macro, the pro-
grammer must be aware that the label symbol is valid for the entire 
body of the current level of macro expansion.  It is not valid for 
any nested macros within the current level of expansion.  The ex-
ample above shows why the local label feature is useful.  If the 
macro N_R_MUL were called several times, there would be several 
_ENDLOOP labels resulting from the macro expansions.  This is ac-
ceptable because each _ENDLOOP label is considered private to a 
particular instance of macro expansion.

It is sometimes desirable to pass local labels as macro arguments 
to be used within the macro as address references (e.g. MOVE  
#_LABEL,R0).  The assembler effectively disallows this, however, 
since underscore label references within a macro invocation are re-
garded as labels local to that expansion of the macro.  A macro 
local label override is provided which causes local symbol lookup 
to have normal scope rather than macro call scope.  If a circumflex 
(^) precedes an expression containing an underscore label, at ex-
pansion the associated term will be evaluated using the normal lo-
cal label list rather than the macro local label list.  The operator 
has no effect on normal labels or outside a macro expansion.

5.4	  MACRO CALLS

When a macro is invoked the statement causing the action is termed 
a macro call.  The syntax of a macro call consists of the following 
fields:

[<label>]	  <macro name>	  [<arguments>]		[<comment>]

The argument field can have the form:

[<arg>[,<arg>,...,<arg>]]

The macro call statement is made up of three fields besides the 
comment field: the <label>, if any, will correspond to the value 
of the location counter at the start of the macro expansion; the 
operation field which contains the macro name; and the operand 
field which contains substitutable arguments.  Within the operand 
field each calling argument of a macro call corresponds one-to-one 
with a dummy argument of the macro definition.  For example, the 
N_R_MUL macro defined earlier could be invoked for expansion 
(called) by the statement:

N_R_MUL		CNT+1,VEC1,VEC2,OUT

where the operand field arguments, separated by commas and taken 
left to right, correspond to the dummy arguments "N" through "RE-
SULT", respectively. These arguments are then substituted in their 
corresponding positions of the definition to produce a sequence of 
instructions.

Macro arguments consist of sequences of characters separated by 
commas.  Although these can be specified as quoted strings, to sim-
plify coding the assembler does not require single quotes around 
macro argument strings.  However, if an argument has an embedded 
comma or space, that argument must be surrounded by single quotes 
(').  An argument can be declared null when calling a macro.  How-
ever, it must be declared explicitly null.  Null arguments can be 
specified in four ways: by writing the delimiting commas in suc-
cession with no intervening spaces, by terminating the argument 
list with a comma and omitting the rest of the argument list, by 
declaring the argument as a null string, or by simply omitting some 
or all of the arguments.  A null argument will cause no character 
to be substituted in the generated statements that reference the 
argument.  If more arguments are supplied in the macro call than 
appear in the macro definition, a warning will be output by the 
assembler.

5.5	  DUMMY ARGUMENT OPERATORS

The assembler macro processor provides for text substitution of ar-
guments during macro expansion.  In order to make the argument sub-
stitution facility more flexible, the assembler also recognizes 
certain text operators within macro definitions which allow for 
transformations of the argument text.  These operators can be used 
for text concatenation, numeric conversion, and string handling.

5.5.1	  Dummy argument concatenation operator - \

Dummy arguments that are intended to be concatenated with other 
characters must be preceded by the concatenation operator, '\' to 
separate them from the rest of the characters. The argument may 
precede or follow the adjoining text, but there must be no inter-
vening blanks between the concatenation operator and the rest of 
the characters. To position an argument between two alphanumeric 
characters, place a backslash both before and after the argument 
name. For example, consider the following macro definition:

SWAP_REG	MACRO	REG1,REG2	;swap REG1,REG2 using X0 as temp
	MOVE	R\REG1,X0
	MOVE	R\REG2,R\REG1
	MOVE	X0,R\REG2
	ENDM

If this macro were called with the following statement,

	SWAP_REG		0,1

then for the macro expansion, the macro processor would substitute 
the character 0 for the dummy argument REG1, and the character 1 
for the dummy argument REG2.  The concatenation operator (\) indi-
cates to the macro processor that the substitution characters for 
the dummy arguments are to be concatenated in both cases with the 
character R.  The resulting expansion of this macro call would be:

	MOVE 	R0,X0
	MOVE 	R1,R0
	MOVE 	X0,R1

5.5.2	  Return value operator - ?

Another macro definition operator is the question mark (?) that 
returns the value of a symbol. When the macro processor encounters 
this operator, the ?<symbol> sequence is converted to a character 
string representing the decimal value of the <symbol>.   For exam-
ple, consider the following modification of the SWAP_REG macro de-
scribed above:

SWAP_SYM	MACRO	REG1,REG2	;swap REG1,REG2 using X0 as temp
	MOVE	R\?REG1,X0
	MOVE	R\?REG2,R\?REG1
	MOVE	X0,R\?REG2
	ENDM

If the source file contained the following SET statements and macro 
call,

AREG	SET 	0
BREG	SET 	1
	SWAP_SYM	AREG,BREG

then the sequence of events would be as follows:  the macro pro-
cessor would first substitute the characters AREG for each occur-
rence of REG1 and BREG for each occurrence of REG2.  For discussion 
purposes (this would never appear on the source listing), the in-
termediate macro expansion would be:

	MOVE	R\?AREG,X0
	MOVE	R\?BREG,R\?AREG
	MOVE	X0,R\?BREG

The macro processor would then replace ?AREG with the character 0 
and ?BREG with the character 1, since 0 is the value of the symbol 
AREG and 1 is the value of BREG. The resulting intermediate expan-
sion would be:

	MOVE	R\0,X0
 	MOVE	R\1,R\0
	MOVE	X0,R\1

Next, the macro processor would apply the concatenation operator 
(\), and the resulting expansion as it would appear on the source 
listing would be:

	MOVE	R0,X0
	MOVE	R1,R0
	MOVE	X0,R1

5.5.3	  Return hex value operator - %

The percent sign (%) is similar to the standard return value oper-
ator except that it returns the hexadecimal value of a symbol. When 
the macro processor encounters this operator, the %<symbol> se-
quence is converted to a character string representing the hexa-
decimal value of the <symbol>. Consider the following macro 
definition:

GEN_LAB	MACRO	LAB,VAL,STMT
LAB\%VAL	STMT
	ENDM

This macro generates a label consisting of the concatenation of the 
label prefix argument and a value that is interpreted as hexadec-
imal.  If this macro were called as follows,

NUM	SET	10
	GEN_LAB	HEX,NUM,'NOP'

the macro processor would first substitute the characters HEX for 
LAB, then it would replace %VAL with the character A, since A is 
the hexadecimal representation for the decimal integer 10. Next, 
the macro processor would apply the concatenation operator (\). Fi-
nally, the string 'NOP' would be substituted for the STMT argument. 
The resulting expansion as it would appear in the listing file 
would be:

HEXA	NOP

The percent sign is also the character used to indicate a binary 
constant.  If a binary constant is required inside a macro it may 
be necessary to enclose the constant in parentheses or escape the 
constant by following the percent sign by a backslash (\).

5.5.4	  Dummy argument string operator - "

Another dummy argument operator is the double quote ("). This char-
acter is replaced with a single quote by the macro processor, but 
following characters are still examined for dummy argument names. 
The effect in the macro call is to transform any enclosed dummy 
arguments into literal strings. For example, consider the following 
macro definition:

STR_MAC	MACRO	STRING
	DC	"STRING"
	ENDM

If this macro were called with the following macro expansion line,

	STR_MAC	ABCD

then the resulting macro expansion would be:

	DC	'ABCD'

Double quotes also make possible DEFINE directive expansion within 
quoted strings.  Because of this overloading of the double quotes, 
care must be taken to insure against inappropriate expansions in 
macro definitions.  Since DEFINE expansion occurs before macro sub-
stitution, any DEFINE symbols are replaced first within a macro 
dummy argument string:

	DEFINE	LONG	'short'
STR_MAC	MACRO	STRING
	MSG	'This is a LONG STRING'
	MSG	"This is a LONG STRING"
	ENDM

If this macro were invoked as follows,

	STR_MAC		sentence

then the resulting expansion would be:

	MSG	'This is a LONG STRING'
	MSG	'This is a short sentence'

5.5.5	  Macro local label override operator - ^

It may be desirable to pass a local label as a macro argument to 
be used as an address reference within the macro body.  If a cir-
cumflex (^) precedes an expression containing an underscore label, 
during macro expansion the associated term will be evaluated with 
normal local label scope rather than macro call scope.  Such in-
terpretation disables the usual local label semantics for this par-
ticular reference within the macro call.  Here is an example:

LOAD	MACRO	ADDR
	MOVE	P:^ADDR,R0
	ENDM

The macro local label override operator causes the ADDR argument 
to be interpreted as a local label outside the macro if the expanded 
argument has a leading underscore.  If there is no leading under-
score on the actual argument then the override operator has no ef-
fect.  Consider the following macro call:

_LOCAL
	LOAD	_LOCAL

Without the local label override in the macro definition, an error 
would occur at the macro call because a symbol _LOCAL was not de-
fined in the body of the macro.  Because the circumflex was used 
the value of _LOCAL gets moved to R0.  Note that any arbitrary 
string may be used as the actual parameter to the LOAD macro.  The 
override operator has an effect only with underscore labels.  Care 
must be exercised, however, in not defining a macro label called 
_LOCAL and attempting to reference it as in the above example.  In 
that case the macro local label override operator prevents the as-
sembler from seeing the local label definition for that reference, 
and an error would result.

5.6	  DUP, DUPA, DUPC, DUPF DIRECTIVES

The DUP, DUPA, DUPC, and DUPF directives are specialized macro 
forms. They can be thought of as a simultaneous definition and call 
of an unnamed macro. The source statements between the DUP, DUPA, 
DUPC, and DUPF directives and the ENDM directive follow the same 
rules as macro definitions, including (in the case of DUPA, DUPC, 
and DUPF) the dummy operator characters described previously. For 
a detailed description of these directives, refer to Chapter 6.

5.7	  CONDITIONAL ASSEMBLY

Conditional assembly facilitates the writing of comprehensive 
source programs that can cover many conditions.  Assembly condi-
tions may be specified through the use of arguments in the case of 
macros, and through definition of symbols via the DEFINE, SET, and 
EQU directives.  Variations of parameters can then cause assembly 
of only those parts necessary for the given conditions.  The built-
in functions of the assembler provide a versatile means of testing 
many conditions of the assembly environment (see Section 3.8 for 
more information on the assembler built-in functions).

Conditional directives can also be used within a macro definition 
to ensure at expansion time that arguments fall within a range of 
allowable values.  In this way macros become self-checking and can 
generate error messages to any desired level of detail.

The conditional assembly directive IF has the following form:

	IF	<expression>
	.
	.
	[ELSE]	(the ELSE directive is optional)
	.
	.
	ENDIF

A section of a program that is to be conditionally assembled must 
be bounded by an IF-ENDIF directive pair.  If the optional ELSE 
directive is not present, then the source statements following the 
IF directive and up to the next ENDIF directive will be included 
as part of the source file being assembled only if the <expression> 
had a nonzero result.  If the <expression> has a value of zero, the 
source file will be assembled as if those statements between the 
IF and the ENDIF directives were never encountered.  If the ELSE 
directive is present and <expression> has a nonzero result, then 
the statements between the IF and ELSE directives will be assem-
bled, and the statements between the ELSE and ENDIF directives will 
be skipped.  Alternatively, if <expression> has a value of zero, 
then the statements between the IF and ELSE directives will be 
skipped, and the statements between the ELSE and ENDIF directives 
will be assembled.


Chapter 6

ASSEMBLER SIGNIFICANT CHARACTERS AND DIRECTIVES

6.1	  INTRODUCTION

This chapter describes the directives that are recognized by the 
Motorola DSP Assembler.  The assembler directives are instructions 
to the assembler rather than instructions to be directly translated 
into object code.  In addition, this chapter describes special 
characters that are considered significant to the assembler.

6.2	  ASSEMBLER SIGNIFICANT CHARACTERS

There are several one and two character sequences that are signif-
icant to the assembler.  Some have multiple meanings depending on 
the context in which they are used.  Special characters associated 
with expression evaluation are described in Chapter 3.  Other as-
sembler-significant characters are:

;	-	Comment delimiter
;;	-	Unreported comment delimiter
\	-	Line continuation character or
		Macro dummy argument concatenation operator
?	-	Macro value substitution operator
%	-	Macro hex value substitution operator
^	-	Macro local label override operator
"	-	Macro string delimiter or
		Quoted string DEFINE expansion character
@	-	Function delimiter
*	-	Location counter substitution
++	-	String concatenation operator
[ ]	-	Substring delimiter
<<	-	I/O short addressing mode force operator
<	-	Short addressing mode force operator
>	-	Long addressing mode force operator
#	-	Immediate addressing mode operator
#<	-	Immediate short addressing mode force operator
#>	-	Immediate long addressing mode force operator

6.3	  ASSEMBLER DIRECTIVES

Assembler directives can be grouped by function into seven types:

1.  Assembly control
2.  Symbol definition
3.  Data definition/storage allocation
4.  Listing control and options
5.  Object file control
6.  Macros and conditional assembly
7.  Structured programming

6.3.1	  Assembly Control

The directives used for assembly control are:

COMMENT	- Start comment lines
DEFINE	- Define substitution string
END 	- End of source program
FAIL	- Programmer generated error message
FORCE	- Set operand forcing mode
HIMEM	- Set high memory bounds
INCLUDE	- Include secondary file
LOMEM	- Set low memory bounds
MODE	- Change relocation mode
MSG	- Programmer generated message
ORG	- Initialize memory space and location 
counters
RADIX	- Change input radix for constants
RDIRECT	- Remove directive or mnemonic from table
SCSJMP	- Set structured control branching mode
SCSREG	- Reassign structured control statement regis-
ters
UNDEF	- Undefine DEFINE symbol
WARN	- Programmer generated warning

6.3.2	  Symbol Definition

The directives used to control symbol definition are:

ENDSEC	- End section
EQU	- Equate symbol to a value
GLOBAL	- Global section symbol declaration
GSET	- Set global symbol to a value
LOCAL	- Local section symbol declaration
SECTION	- Start section
SET	- Set symbol to a value
XDEF	- External section symbol definition
XREF	- External section symbol reference

6.3.3	  Data Definition/Storage Allocation

The directives used to control constant data definition and storage 
allocation are:

BADDR	- Set buffer address
BSB	- Block storage bit-reverse
BSC	- Block storage of constant
BSM	- Block storage modulo
BUFFER	- Start buffer
DC	- Define constant
DCB	- Define constant byte
DS	- Define storage
DSM	- Define modulo storage
DSR	- Define reverse carry storage
ENDBUF	- End buffer

6.3.4	  Listing Control and Options

The directives used to control the output listing are:

LIST	- List the assembly
LSTCOL	- Set listing field widths
NOLIST	- Stop assembly listing
OPT	- Assembler options
PAGE	- Top of page/size page
PRCTL	- Send control string to printer
STITLE	- Initialize program subtitle
TABS	- Set listing tab stops
TITLE	- Initialize program title

6.3.5	  Object File Control

The directives used for control of the object file are:

COBJ	- Comment object code
IDENT	- Object code identification record
SYMOBJ	- Write symbol information to object file

6.3.6	  Macros and Conditional Assembly

The directives used for macros and conditional assembly are:

DUP	- Duplicate sequence of source lines
DUPA	- Duplicate sequence with arguments
DUPC	- Duplicate sequence with characters
DUPF	- Duplicate sequence in loop
ENDIF	- End of conditional assembly
ENDM	- End of macro definition
EXITM	- Exit macro
IF	- Conditional assembly directive
MACLIB	- Macro library
MACRO	- Macro definition
PMACRO	- Purge macro definition

6.3.7	  Structured Programming

The directives used for structured programming are:

.BREAK	- Exit from structured loop construct
.CONTINUE	- Continue next iteration of structured loop
.ELSE	- Perform following statements when .IF false
.ENDF	- End of .FOR loop
.ENDI	- End of .IF condition
.ENDL	- End of hardware loop
.ENDW	- End of .WHILE loop
.FOR	- Begin .FOR loop
.IF	- Begin .IF condition
.LOOP	- Begin hardware loop
.REPEAT	- Begin .REPEAT loop
.UNTIL	- End of .REPEAT loop
.WHILE	- Begin .WHILE loop

Individual descriptions of each of the assembler special characters 
and directives follow.  They include usage guidelines, functional 
descriptions, and examples.  Some directives require a label field, 
while in many cases a label is optional.  If the description of an 
assembler directive does not indicate a mandatory or optional label 
field, then a label is not allowed on the same line as the direc-
tive.  Structured programming directives are discussed separately 
in Chapter 7.

;
Comment Delimiter Character

Any number of characters preceded by a semicolon (;), but not part 
of a literal string, is considered a comment.  Comments are not 
significant to the assembler, but they can be used to document the 
source program.  Comments will be reproduced in the assembler out-
put listing.  Comments are normally preserved in macro definitions, 
but this option can be turned off (see the OPT directive, this chap-
ter).

Comments can occupy an entire line, or can be placed after the last 
assembler-significant field in a source statement.  A comment 
starting in the first column of the source file will be aligned 
with the label field in the listing file.  Otherwise, the comment 
will be shifted right and aligned with the comment field in the 
listing file.

EXAMPLE:

; THIS COMMENT BEGINS IN COLUMN 1 OF THE SOURCE FILE

LOOP	JSR	COMPUTE	; THIS IS A TRAILING COMMENT
			; THESE TWO COMMENTS ARE PRECEDED
			; BY A TAB IN THE SOURCE FILE

;;
 Unreported Comment Delimiter Characters

Unreported comments are any number of characters preceded by two 
consecutive semicolons (;;) that are not part of a literal string. 
Unreported comments are not considered significant by the assem-
bler, and can be included in the source statement, following the 
same rules as normal comments. However, unreported comments are 
never reproduced on the assembler output listing, and are never 
saved as part of macro definitions.

EXAMPLE:

;; THESE LINES WILL NOT BE REPRODUCED
;; IN THE SOURCE LISTING

\
Line Continuation Character or
Macro Argument Concatenation Character

Line Continuation

The backslash character (\), if used as the last character on a 
line, indicates to the assembler that the source statement is con-
tinued on the following line. The continuation line will be con-
catenated to the previous line of the source statement, and the 
result will be processed by the assembler as if it were a single 
line source statement. The maximum source statement length (the 
first line and any continuation lines) is 512 characters. 

EXAMPLE:

; THIS COMMENT \
EXTENDS OVER \
THREE LINES

Macro Argument Concatenation

The backslash (\) is also used to cause the concatenation of a macro 
dummy argument with other adjacent alphanumeric characters.  For 
the macro processor to recognize dummy arguments, they must nor-
mally be separated from other alphanumeric characters by a non-
symbol character.  However, sometimes it is desirable to concate-
nate the argument characters with other characters.  If an argument 
is to be concatenated in front of or behind some other symbol char-
acters, then it must be followed by or preceded by the backslash, 
respectively.

EXAMPLE:

Suppose the source input file contained the following macro defi-
nition:

SWAP_REG	MACRO	REG1,REG2	;swap REG1,REG2 using D4.L as temp
	MOVE	R\REG1,D4.L
	MOVE	R\REG2,R\REG1
	MOVE	D4.L,R\REG2
	ENDM

The concatenation operator (\) indicates to the macro processor 
that the substitution characters for the dummy arguments are to be 
concatenated in both cases with the character R.  If this macro 
were called with the following statement,

	SWAP_REG		0,1

the resulting expansion would be:

	MOVE	R0,D4.L
	MOVE	R1,R0
	MOVE	D4.L,R1

?
Return Value of Symbol Character

The ?<symbol> sequence, when used in macro definitions, will be 
replaced by an ASCII string representing the value of <symbol>. 
This operator may be used in association with the backslash (\) 
operator. The value of <symbol> must be an integer (not floating 
point).

EXAMPLE:

Consider the following macro definition:

SWAP_SYM	MACRO	REG1,REG2	;swap REG1,REG2 using D4.L as temp
	MOVE	R\?REG1,D4.L
	MOVE	R\?REG2,R\?REG1
 	MOVE	D4.L,R\?REG2
	ENDM

If the source file contained the following SET statements and macro 
call,

AREG	SET	0
BREG	SET	1
	SWAP_SYM	AREG,BREG

the resulting expansion as it would appear on the source listing 
would be:

	MOVE	R0,D4.L
	MOVE	R1,R0
	MOVE	D4.L,R1

%
Return Hex Value of Symbol Character

The %<symbol> sequence, when used in macro definitions, will be 
replaced by an ASCII string representing the hexadecimal value of 
<symbol>. This operator may be used in association with the back-
slash (\) operator. The value of <symbol> must be an integer (not 
floating point).

EXAMPLE:

Consider the following macro definition:

GEN_LAB	MACRO	LAB,VAL,STMT
LAB\%VAL	STMT
	ENDM

If this macro were called as follows,

NUM	SET	10
	GEN_LAB	HEX,NUM,'NOP'

The resulting expansion as it would appear in the listing file 
would be:

HEXA	NOP

^
Macro Local Label Override

The circumflex (^), when used as a unary expression operator in a 
macro expansion, will cause any local labels in its associated term 
to be evaluated at normal scope rather than macro scope.  This means 
that any underscore labels in the expression term following the 
circumflex will not be searched for in the macro local label list.  
The operator has no effect on normal labels or outside of a macro 
expansion.  The circumflex operator is useful for passing local 
labels as macro arguments to be used as referents in the macro.  
Note that the circumflex is also used as the binary exclusive OR 
operator.

EXAMPLE:

Consider the following macro definition:

LOAD	MACRO	ADDR
	MOVE	P:^ADDR,R0
	ENDM

If this macro were called as follows,

_LOCAL
	LOAD	_LOCAL

the assembler would ordinarily issue an error since _LOCAL is not 
defined within the body of the macro.  With the override operator 
the assembler recognizes the _LOCAL symbol outside the macro ex-
pansion and uses that value in the MOVE instruction.

"
Macro String Delimiter or
Quoted String DEFINE Expansion Character

Macro String

The double quote ("), when used in macro definitions, is trans-
formed by the macro processor into the string delimiter, the single 
quote ('). The macro processor examines the characters between the 
double quotes for any macro arguments. This mechanism allows the 
use of macro arguments as literal strings.

EXAMPLE:

Using the following macro definition,

CSTR	MACRO	STRING
	DC	"STRING"
	ENDM

and a macro call,

	CSTR	ABCD

the resulting macro expansion would be:

	DC	'ABCD'

Quoted String DEFINE Expansion

A sequence of characters which matches a symbol created with a DE-
FINE directive will not be expanded if the character sequence is 
contained within a quoted string. Assembler strings generally are 
enclosed in single quotes ('). If the string is enclosed in double 
quotes (") then DEFINE symbols will be expanded within the string. 
In all other respects usage of double quotes is equivalent to that 
of single quotes.

EXAMPLE:

Consider the source fragment below:

	DEFINE	LONG	'short'
STR_MAC	MACRO	STRING
	MSG	'This is a LONG STRING'
	MSG	"This is a LONG STRING"
	ENDM

If this macro were invoked as follows,

	STR_MAC	sentence

then the resulting expansion would be:

	MSG	'This is a LONG STRING'
	MSG	'This is a short sentence'

@
Function Delimiter

All assembler built-in functions start with the @ symbol.  See Sec-
tion 3.8 for a full discussion of these functions.

EXAMPLE:

SVAL	EQU	@SQT(FVAL)	; OBTAIN SQUARE ROOT

*
Location Counter Substitution

When used as an operand in an expression, the asterisk represents 
the current integer value of the runtime location counter.

EXAMPLE:

	ORG	X:$100

XBASE	EQU	*+$20	; XBASE = $120

++
String Concatenation Operator

Any two strings can be concatenated with the string concatenation 
operator (++).  The two strings must each be enclosed by single or 
double quotes, and there must be no intervening blanks between the 
string concatenation operator and the two strings.

EXAMPLE:

	'ABC'++'DEF' = 'ABCDEF'

[ ]
Substring Delimiter

	[<string>,<offset><length>]

Square brackets delimit a substring operation.  The <string> argu-
ment is the source string.  <offset> is the substring starting po-
sition within <string>.  <length> is the length of the desired 
substring.  <string> may be any legal string combination, including 
another substring.  An error is issued if either <offset> or 
<length> exceed the length of <string>.

EXAMPLE:

	DEFINE	ID	['DSP56000',3,5]		; ID = '56000'

<<
I/O Short Addressing Mode Force Operator

Many DSP instructions allow an I/O short form of addressing.  If 
the value of an absolute address is known to the assembler on pass 
one, then the assembler will always pick the shortest form of ad-
dressing consistent with the instruction format.  If the absolute 
address is not known to the assembler on pass one (that is, the 
address is a forward or external reference), then the assembler 
will pick the long form of addressing by default.  If this is not 
desired, then the I/O short form of addressing can be forced by 
preceding the absolute address by the I/O short addressing mode 
force operator (<<).

EXAMPLE:

Since the symbol IOPORT is a forward reference in the following 
sequence of source lines, the assembler would pick the long abso-
lute form of addressing by default:

	BTST	#4,Y:IOPORT
IOPORT	EQU	Y:$FFF3

Because the long absolute addressing mode would cause the instruc-
tion to be two words long instead of one word for the I/O short 
absolute addressing mode, it would be desirable to force the I/O 
short absolute addressing mode as shown below:

	BTST	#4,Y:<<IOPORT
IOPORT	EQU	Y:$FFF3

<
Short Addressing Mode Force Operator

Many DSP instructions allow a short form of addressing.  If the 
value of an absolute address is known to the assembler on pass one, 
or the FORCE SHORT directive is active, then the assembler will 
always pick the shortest form of addressing consistent with the 
instruction format.  If the absolute address is not known to the 
assembler on pass one (that is, the address is a forward or external 
reference), then the assembler will pick the long form of address-
ing by default.  If this is not desired, then the short absolute 
form of addressing can be forced by preceding the absolute address 
by the short addressing mode force operator (<).

See also:  FORCE

EXAMPLE:

Since the symbol DATAST is a forward reference in the following 
sequence of source lines, the assembler would pick the long abso-
lute form of addressing by default:

	MOVE	D0.L,Y:DATAST
DATAST	EQU	Y:$23

Because the long absolute addressing mode would cause the instruc-
tion to be two words long instead of one word for the  short abso-
lute addressing mode, it would be desirable to force the short 
absolute addressing mode as shown below:

	MOVE	D0.L,Y:<DATAST
DATAST	EQU	Y:$23

>
Long Addressing Mode Force Operator

Many DSP instructions allow a long form of addressing.  If the value 
of an absolute address is known to the assembler on pass one, then 
the assembler will always pick the shortest form of addressing con-
sistent with the instruction format, unless the FORCE LONG direc-
tive is active.  If this is not desired, then the long absolute 
form of addressing can be forced by preceding the absolute address 
by the long addressing mode force operator (>).

See also:  FORCE

EXAMPLE:

Since the symbol DATAST is a not a forward reference in the fol-
lowing sequence of source lines, the assembler would pick the short 
absolute form of addressing:

DATAST	EQU	Y:$23
	MOVE	D0.L,Y:DATAST

If this is not desirable, then the long absolute addressing mode 
can be forced as shown below:

DATAST	EQU	Y:$23
	MOVE	D0.L,Y:>DATAST

#
Immediate Addressing Mode

The pound sign (#) is used to indicate to the assembler to use the 
immediate addressing mode.

EXAMPLE:

CNST	EQU	$5
	MOVE	#CNST,D0.L

#<
Immediate Short Addressing Mode Force Operator

Many DSP instructions allow a short immediate form of addressing.  
If the immediate data is known to the assembler on pass one (not a 
forward or external reference), or the FORCE SHORT directive is 
active, then the assembler will always pick the shortest form of 
immediate addressing consistent with the instruction.  If the im-
mediate data is a forward or external reference, then the assembler 
will pick the long form of immediate addressing by default.  If 
this is not desired, then the short form of addressing can be forced 
using the immediate short addressing mode force operator (#<).

See also:  FORCE

EXAMPLE:

In the following sequence of source lines, the symbol CNST is not 
known to the assembler on pass one, and therefore, the assembler 
would use the long immediate addressing form for the MOVE instruc-
tion.

	MOVE	#CNST,D0.L
CNST	EQU	$5

Because the long immediate addressing mode makes the instruction 
two words long instead of one word for the immediate short address-
ing mode, it may be desirable to force the immediate short address-
ing mode as shown below:

	MOVE	#<CNST,D0.L
CNST	EQU	$5

#>
Immediate Long Addressing Mode Force Operator

Many DSP instructions allow a long immediate form of addressing.  
If the immediate data is known to the assembler on pass one (not a 
forward or external reference), then the assembler will always pick 
the shortest form of immediate addressing consistent with the in-
struction, unless the FORCE LONG directive is active.  If this is 
not desired, then the long form of addressing can be forced using 
the immediate long addressing mode force operator (#>).

See also:  FORCE

EXAMPLE:

In the following sequence of source lines, the symbol CNST is  known 
to the assembler on pass one, and therefore, the assembler would 
use the short immediate addressing form for the MOVE instruction.

CNST	EQU	$5
	MOVE	#CNST,D0.L

If this is not desirable, then the long immediate form of address-
ing can be forced as shown below:

CNST	EQU	$5
	MOVE	#>CNST,D0.L

BADDR
Set Buffer Address

	BADDR	<M | R>,<expression>

The BADDR directive sets the runtime location counter to the ad-
dress of a buffer of the given type, the length of which in words 
is equal to the value of <expression>. The buffer type may be either 
Modulo or Reverse-carry. If the runtime location counter is not 
zero, this directive first advances the runtime location counter 
to a base address that is a multiple of 2k, where 2k >= <expres-
sion>. An error will be issued if there is insufficient memory re-
maining to establish a valid base address. Unlike other buffer 
allocation directives, the runtime location counter is not advanced 
by the value of the integer expression in the operand field; the 
location counter remains at the buffer base address. The block of 
memory intended for the buffer is not initialized to any value.

The result of <expression> may have any memory space attribute but 
must be an absolute integer greater than zero and cannot contain 
any forward references (symbols that have not yet been defined). 
If a Modulo buffer is specified, the expression must fall within 
the range 2 <= <expression> <= m, where m is the maximum address 
of the target DSP. If a Reverse-carry buffer is designated and <ex-
pression> is not a power of two a warning will be issued.

A label is not allowed with this directive.

See also:  BSM, BSB, BUFFER, DSM, DSR

EXAMPLE:

	ORG	X:$100
M_BUF	BADDR	M,24	; CIRCULAR BUFFER MOD 24

BSB
Block Storage Bit-Reverse

[<label>]	  BSB	<expression>[,<expression>]

The BSB directive causes the assembler to allocate and initialize 
a block of words for a reverse-carry buffer. The number of words 
in the block is given by the first expression, which must evaluate 
to an absolute integer. Each word is assigned the initial value of 
the second expression. If there is no second expression, an initial 
value of zero is assumed. If the runtime location counter is not 
zero, this directive first advances the runtime location counter 
to a base address that is a multiple of 2k, where 2k is greater 
than or equal to the value of the first expression. An error will 
occur if the first expression contains symbols that are not yet 
defined (forward references) or if the expression has a value of 
less than or equal to zero. Also, if the first expression is not a 
power of two a warning will be generated. Both expressions can have 
any memory space attribute.

<label>, if present, will be assigned the value of the runtime lo-
cation counter after a valid base address has been established.

Only one word of object code will be shown on the listing, regard-
less of how large the first expression is.  However, the runtime 
location counter will be advanced by the number of words generated.

See also:  BSC, BSM, DC

EXAMPLE:

BUFFER	  BSB	  BUFSIZ	  ; INITIALIZE BUFFER TO ZEROS

BSC
Block Storage of Constant

[<label>]	  BSC	<expression>[,<expression>]

The BSC directive causes the assembler to allocate and initialize 
a block of words.  The number of words in the block is given by the 
first expression, which must evaluate to an absolute integer.  Each 
word is assigned the initial value of the second expression.  If 
there is no second expression, an initial value of zero is assumed.  
If the first expression contains symbols that are not yet defined 
(forward references) or if the expression has a value of less than 
or equal to zero, an error will be generated.  Both expressions can 
have any memory space attribute.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the directive processing.

Only one word of object code will be shown on the listing, regard-
less of how large the first expression is.  However, the runtime 
location counter will be advanced by the number of words generated.

See also:  BSM, BSB, DC

EXAMPLE:

UNUSED	  BSC	  $2FFF-@LCV(R),$FFFFFFFF	  ; FILL UNUSED EPROM

BSM
Block Storage Modulo

[<label>]	  BSM	<expression>[,<expression>]

The BSM directive causes the assembler to allocate and initialize 
a block of words for a modulo buffer. The number of words in the 
block is given by the first expression, which must evaluate to an 
absolute integer. Each word is assigned the initial value of the 
second expression. If there is no second expression, an initial 
value of zero is assumed. If the runtime location counter is not 
zero, this directive first advances the runtime location counter 
to a base address that is a multiple of 2k, where 2k is greater 
than or equal to the value of the first expression. An error will 
occur if the first expression contains symbols that are not yet 
defined (forward references), has a value of less than or equal to 
zero, or falls outside the range 2 <= <expression> <= m, where m 
is the maximum address of the target DSP. Both expressions can have 
any memory space attribute.

<label>, if present, will be assigned the value of the runtime lo-
cation counter after a valid base address has been established.

Only one word of object code will be shown on the listing, regard-
less of how large the first expression is.  However, the runtime 
location counter will be advanced by the number of words generated.

See also:  BSC, BSB, DC

EXAMPLE:

BUFFER	  BSM	  BUFSIZ,$FFFFFFFF	  ; INITIALIZE BUFFER TO ALL 
ONES

BUFFER
Start Buffer

	  BUFFER	<M | R>,<expression>

The BUFFER directive indicates the start of a buffer of the given 
type.  Data is allocated for the buffer until an ENDBUF directive 
is encountered.  Instructions and most data definition directives 
may appear between the BUFFER and ENDBUF pair, although BUFFER di-
rectives may not be nested and certain types of directives such as 
MODE, ORG, SECTION, and other buffer allocation directives may not 
be used.  The <expression> represents the buffer size.  If less 
data is allocated than the size of the buffer, the remaining buffer 
locations will be uninitialized.  If more data is allocated than 
the specified size of the buffer, an error is issued.

The BUFFER directive sets the runtime location counter to the ad-
dress of a buffer of the given type, the length of which in words 
is equal to the value of <expression>. The buffer type may be either 
Modulo or Reverse-carry. If the runtime location counter is not 
zero, this directive first advances the runtime location counter 
to a base address that is a multiple of 2k, where 2k >= <expres-
sion>. An error will be issued if there is insufficient memory re-
maining to establish a valid base address. Unlike other buffer 
allocation directives, the runtime location counter is not advanced 
by the value of the integer expression in the operand field; the 
location counter remains at the buffer base address.

The result of <expression> may have any memory space attribute but 
must be an absolute integer greater than zero and cannot contain 
any forward references (symbols that have not yet been defined).  
If a Modulo buffer is specified, the expression must fall within 
the range 2 <= <expression> <= m, where m is the maximum address 
of the target DSP.  If a Reverse-carry buffer is designated and 
<expression> is not a power of two a warning will be issued.

A label is not allowed with this directive.

See also:  BADDR, BSM, BSB, DSM, DSR, ENDBUF

EXAMPLE:

	ORG	X:$100
	BUFFER	M,24	; CIRCULAR BUFFER MOD 24
M_BUF	DC	0.5,0.5,0.5,0.5
	DS	20	; REMAINDER UNINITIALIZED
	ENDBUF

COBJ
Comment Object File

	COBJ	<string>

The COBJ directive is used to place a comment in the object code 
file.  The <string> will be put in the object file as a comment  
(refer to the object format description in  Appendix E).

A label is not allowed with this directive.

See also:  IDENT

EXAMPLE:

	COBJ	'Start of filter coefficients'

COMMENT
Start Comment Lines

	COMMENT	  <delimiter>
	.
	.
	<delimiter>

The COMMENT directive is used to define one or more lines as com-
ments.  The first non-blank character after the COMMENT directive 
is the comment delimiter.  The two delimiters are used to define 
the comment text.  The line containing the second comment delimiter 
will be considered the last line of the comment.  The comment text 
can include any printable characters and the comment text will be 
reproduced in the source listing as it appears in the source file.

A label is not allowed with this directive.

EXAMPLE:

	COMMENT	  + This is a one line comment +
	COMMENT	  *	This is a multiple line
			comment.  Any number of lines
			can be placed between the two de-
limiters.
		  *

DC
Define Constant

[<label>]	  DC	  <arg>[,<arg>,...,<arg>]

The DC directive allocates and initializes a word of memory for 
each <arg> argument.  <arg> may be a numeric constant, a single or 
multiple character string constant, a symbol, or an expression.  
The DC directive may have one or more arguments separated by com-
mas.  Multiple arguments are stored in successive address loca-
tions.  If multiple arguments are present, one or more of them can 
be null (two adjacent commas), in which case the corresponding ad-
dress location will be filled with zeros.  If the DC directive is 
used in L memory, the arguments will be evaluated and stored as 
long word quantities.  Otherwise, an error will occur if the eval-
uated argument value is too large to represent in a single DSP word.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the directive processing.

Integer arguments are stored as is; floating point numbers are con-
verted to binary values.  Single and multiple character strings are 
handled in the following manner:

1.	Single character strings are stored in a word whose lower 
seven bits represent the ASCII value of the character.

EXAMPLE:		'R'	= $000052

2.	Multiple character strings represent words whose bytes 
are composed of concatenated sequences of the ASCII represen-
tation of the characters in the string (unless the NOPS option 
is specified; see the OPT directive).  If the number of char-
acters is not an even multiple of  the number of bytes per DSP 
word, then the last word will have the remaining characters 
left aligned and the rest of the word will be zero-filled.  If 
the NOPS option is given, each character in the string is 
stored in a word whose lower seven bits represent the ASCII 
value of the character.

EXAMPLE:	

'ABCD'	=	$414243
		$440000

See also:  BSC, DCB

EXAMPLE:

TABLE	DC	1426,253,$2662,'ABCD'
CHARS	DC	'A','B','C','D'

DCB
Define Constant Byte

[<label>]	  DCB	  <arg>[,<arg>,...,<arg>]

The DCB directive allocates and initializes a byte of memory for 
each <arg> argument.  <arg> may be a byte integer constant, a single 
or multiple character string constant, a symbol, or a byte expres-
sion.  The DCB directive may have one or more arguments separated 
by commas.  Multiple arguments are stored in successive byte loca-
tions.  If multiple arguments are present, one or more of them can 
be null (two adjacent commas), in which case the corresponding byte 
location will be filled with zeros.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the directive processing.

Integer arguments are stored as is, but must be byte values (e.g. 
within the range 0-255); floating point numbers are not allowed.  
Single and multiple character strings are handled in the following 
manner:

1.	Single character strings are stored in a word whose lower 
seven bits represent the ASCII value of the character.

EXAMPLE:		'R'	= $000052

2.	Multiple character strings represent words whose bytes 
are composed of concatenated sequences of the ASCII represen-
tation of the characters in the string (unless the NOPS option 
is specified; see the OPT directive).  If the number of char-
acters is not an even multiple of  the number of bytes per DSP 
word, then the last word will have the remaining characters 
left aligned and the rest of the word will be zero-filled.  If 
the NOPS option is given, each character in the string is 
stored in a word whose lower seven bits represent the ASCII 
value of the character.

EXAMPLE:	

'AB',,'CD'	=	$414200
		$434400

See also:  BSC, DC

EXAMPLE:

TABLE	DCB	'two',0,'strings',0
CHARS	DCB	'A','B','C','D'

DEFINE
Define Substitution String

	DEFINE	<symbol>	<string>

The DEFINE directive is used to define substitution strings that 
will be used on all following source lines. All succeeding lines 
will be searched for an occurrence of <symbol>, which will be re-
placed by <string>. This directive is useful for providing better 
documentation in the source program. <symbol> must adhere to the 
restrictions for non-local labels. That is, it cannot exceed 512 
characters, the first of which must be alphabetic, and the remain-
der of which must be either alphanumeric or the underscore(_). A 
warning will result if a new definition of a previously defined 
symbol is attempted. The assembler output listing will show lines 
after the DEFINE directive has been applied and therefore redefined 
symbols will be replaced by their substitution strings (unless the 
NODXL option in effect; see the OPT directive).

Macros represent a special case.  DEFINE directive translations 
will be applied to the macro definition as it is encountered.  When 
the macro is expanded any active DEFINE directive translations will 
again be applied.

DEFINE directive symbols that are defined within a section will 
only apply to that section.  See the SECTION directive.

A label is not allowed with this directive.

See also:  UNDEF

EXAMPLE:

If the following DEFINE directive occurred in the first part of the 
source program:

	DEFINE	ARRAYSIZ	'10 * SAMPLSIZ'

then the source line below:

	DS	ARRAYSIZ

would be transformed by the assembler to the following:

	DS	10 * SAMPLSIZ

DS
Define Storage

[<label>]	  DS	  <expression>

The DS directive reserves a block of memory the length of which in 
words is equal to the value of <expression>.  This directive causes 
the runtime location counter to be advanced by the value of the 
absolute integer expression in the operand field.  <expression> can 
have any memory space attribute.  The block of memory reserved is 
not initialized to any value.  The expression must be an integer 
greater than zero and cannot contain any forward references (sym-
bols that have not yet been defined).

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the directive processing.

See also: DSM, DSR

EXAMPLE:

S_BUF	DS	12	; SAMPLE BUFFER

DSM
Define Modulo Storage

[<label>]	  DSM	<expression>

The DSM directive reserves a block of memory the length of which 
in words is equal to the value of <expression>. If the runtime lo-
cation counter is not zero, this directive first advances the runt-
ime location counter to a base address that is a multiple of 2k, 
where 
2k >= <expression>. An error will be issued if there is insufficient 
memory remaining to establish a valid base address. Next the runt-
ime location counter is advanced by the value of the integer ex-
pression in the operand field. <expression> can have any memory 
space attribute. The block of memory reserved is not initialized 
to any given value. The result of <expression> must be an absolute 
integer greater than zero and cannot contain any forward references 
(symbols that have not yet been defined). The expression also must 
fall within the range 2 <= <expression> <= m, where m is the maximum 
address of the target DSP.

<label>, if present, will be assigned the value of the runtime lo-
cation counter after a valid base address has been established.

See also: DS, DSR

EXAMPLE:

	ORG	  X:$100
M_BUF	DSM	  24	; CIRCULAR BUFFER MOD 24

DSR
Define Reverse Carry Storage

[<label>]	  DSR	<expression>

The DSR directive reserves a block of memory the length of which 
in words is equal to the value of <expression>. If the runtime lo-
cation counter is not zero, this directive first advances the runt-
ime location counter to a base address that is a multiple of 2k, 
where 
2k >= <expression>. An error will be issued if there is insuffi-
cient memory remaining to establish a valid base address. Next the 
runtime location counter is advanced by the value of the integer 
expression in the operand field. <expression> can have any memory 
space attribute. The block of memory reserved is not initialized 
to any given value. The result of <expression> must be an absolute 
integer greater than zero and cannot contain any forward references 
(symbols that have not yet been defined). Since the DSR directive 
is useful mainly for generating FFT buffers, if <expression> is not 
a power of two a warning will be generated.

<label>, if present, will be assigned the value of the runtime lo-
cation counter after a valid base address has been established.

See also: DS, DSM

EXAMPLE:

	ORG	  X:$100
R_BUF	DSR	  8	; REVERSE CARRY BUFFER FOR 16 POINT FFT

DUP
Duplicate Sequence of Source Lines

[<label>]	  DUP	<expression>
	  .
	  .
	  ENDM

The sequence of source lines between the DUP and ENDM directives 
will be duplicated by the number specified by the integer <expres-
sion>.  <expression> can have any memory space attribute.  If the 
expression evaluates to a number less than or equal to 0, the se-
quence of lines will not be included in the assembler output.  The 
expression result must be an absolute integer and cannot contain 
any forward references (symbols that have not already been de-
fined).  The DUP directive may be nested to any level.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the DUP directive processing.

See also:  DUPA, DUPC, DUPF, ENDM, MACRO

EXAMPLE:

The sequence of source input statements,

COUNT	SET	3
	DUP	COUNT	; ASR BY COUNT
	ASR	D0
	ENDM

would generate the following in the source listing:

COUNT	SET	3
	DUP	COUNT	; ASR BY COUNT
	ASR	D0
	ASR	D0
	ASR	D0
	ENDM

Note that the lines

	DUP	COUNT	;ASR BY COUNT
	ENDM

will only be shown on the source listing if the MD option is en-
abled.  The lines

	ASR	D0
	ASR	D0
	ASR	D0

will only be shown on the source listing if the MEX option is en-
abled.

See the OPT directive in this chapter for more information on the 
MD and MEX options.

DUPA
Duplicate Sequence With Arguments

[<label>]	DUPA	  <dummy>,<arg>[<,<arg>,...,<arg>]
	.
	.
	ENDM

The block of source statements defined by the DUPA and ENDM direc-
tives will be repeated for each argument.  For each repetition, 
every occurrence of the dummy parameter within the block is re-
placed with each succeeding argument string.  If the argument 
string is a null, then the block is repeated with each occurrence 
of the dummy parameter removed.  If an argument includes an embed-
ded blank or other assembler-significant character, it must be en-
closed with single quotes.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the DUPA directive processing.

See also:  DUP, DUPC, DUPF, ENDM, MACRO

EXAMPLE:

If the input source file contained the following statements,

	DUPA	VALUE,12,32,34
	DC	VALUE
	ENDM

then the assembled source listing would show

	DUPA	VALUE,12,32,34
	DC	12
	DC	32
	DC	34
	ENDM

Note that the lines

	DUPA	VALUE,12,32,34
	ENDM

will only be shown on the source listing if the MD option is en-
abled.  The lines

	DC	12
	DC	32
	DC	34

will only be shown on the source listing if the MEX option is en-
abled.

See the OPT directive in this chapter for more information on the 
MD and MEX options.

DUPC
Duplicate Sequence With Characters

[<label>]	  DUPC	<dummy>,<string>
	  .
	  .
	  ENDM

The block of source statements defined by the DUPC and ENDM direc-
tives will be repeated for each character of <string>.  For each 
repetition, every occurrence of the dummy parameter within the 
block is replaced with each succeeding character in the string.  If 
the string is null, then the block is skipped.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the DUPC directive processing.

See also:  DUP, DUPA, DUPF, ENDM, MACRO

EXAMPLE:

If input source file contained the following statements,

	DUPC	VALUE,'123'
	DC	VALUE
	ENDM

then the assembled source listing would show:

	DUPC	VALUE,'123'
	DC	1
	DC	2
	DC	3
	ENDM

Note that the lines

	DUPC	VALUE,'123'
	ENDM

will only be shown on the source listing if the MD option is en-
abled.  The lines

	DC	1
	DC	2
	DC	3

will only be shown on the source listing if the MEX option is en-
abled.

See the OPT directive in this chapter for more information on the 
MD and MEX options.

DUPF
Duplicate Sequence In Loop

[<label>]	  DUPF	<dummy>,[<start>],<end>[,<increment>]
	  .
	  .
	  ENDM

The block of source statements defined by the DUPF and ENDM direc-
tives will be repeated in general (<end> - <start>) + 1 times when 
<increment> is 1.  <start> is the starting value for the loop index; 
<end> represents the final value.  <increment> is the increment for 
the loop index; it defaults to 1 if omitted (as does the <start> 
value).  The <dummy> parameter holds the loop index value and may 
be used within the body of instructions.

<label>, if present, will be assigned the value of the runtime lo-
cation counter at the start of the DUPF directive processing.

See also:  DUP, DUPA, DUPC, ENDM, MACRO

EXAMPLE:

If input source file contained the following statements,

	DUPF	NUM,0,7
	MOVE	#0,R\NUM
	ENDM

then the assembled source listing would show:

	DUPF	NUM,0,7
	MOVE	#0,R0
	MOVE	#0,R1
	MOVE	#0,R2
	MOVE	#0,R3
	MOVE	#0,R4
	MOVE	#0,R5
	MOVE	#0,R6
	MOVE	#0,R7
	ENDM

Note that the lines

	DUPF	NUM,0,7
	ENDM

will only be shown on the source listing if the MD option is en-
abled.  The lines

	MOVE	#0,R0
	MOVE	#0,R1
	MOVE	#0,R2
	MOVE	#0,R3
	MOVE	#0,R4
	MOVE	#0,R5
	MOVE	#0,R6
	MOVE	#0,R7

will only be shown on the source listing if the MEX option is en-
abled.

See the OPT directive in this chapter for more information on the 
MD and MEX options.

END
End of Source Program

	END	  [<expression>]

The optional END directive indicates that the logical end of the 
source program has been encountered.  Any statements following the 
END directive are ignored.  The optional expression in the operand 
field can be used to specify the starting execution address of the 
program.  <expression> may be absolute or relocatable, but must 
have a memory space attribute of Program or None.  The END directive 
cannot be used in a macro expansion.

A label is not allowed with this directive.

EXAMPLE:

	END	BEGIN	; BEGIN is the starting execution 
address

ENDBUF
End Buffer

	ENDBUF

The ENDBUF directive is used to signify the end of a buffer block.  
The runtime location counter will remain just beyond the end of the 
buffer when the ENDBUF directive is encountered.

A label is not allowed with this directive.

See also:  BUFFER

EXAMPLE:

	ORG	X:$100
BUF	BUFFER	R,64	; uninitialized reverse-carry 
buffer
	ENDBUF

ENDIF
End of Conditional Assembly

	ENDIF

The ENDIF directive is used to signify the end of the current level 
of conditional assembly.  Conditional assembly directives can be 
nested to any level, but the ENDIF directive always refers to the 
most previous IF directive.

A label is not allowed with this directive.

See also:  IF

EXAMPLE:

	IF	@REL()
SAVEPC	SET	*	; Save current program counter
	ENDIF

ENDM
End of Macro Definition

	ENDM

Every MACRO, DUP, DUPA, and DUPC directive must be terminated by 
an ENDM directive.

A label is not allowed with this directive.

See also:  DUP, DUPA, DUPC, MACRO

EXAMPLE:

SWAP_SYM	MACRO	REG1,REG	;swap REG1,REG2 using D4.L as 
temp
	MOVE	R\?REG1,D4.L
	MOVE	R\?REG2,R\?REG1
 	MOVE	D4.L,R\?REG2
	ENDM

ENDSEC
End Section

	ENDSEC

Every SECTION directive must be terminated by an ENDSEC directive.

A label is not allowed with this directive.

See also:  SECTION

EXAMPLE:

	SECTION	COEFF
	ORG	Y:
VALUES	BSC	$100	; Initialize to zero
	ENDSEC

EQU
Equate Symbol to a Value

<label>	EQU [{X: | Y: | L: | P: | E:}]<expression>

The EQU directive assigns the value and memory space attribute of 
<expression> to the symbol <label>.  If <expression> has a memory 
space attribute of None, then it can optionally be preceded by any 
of the indicated memory space qualifiers to force a memory space 
attribute.  An error will occur if the expression has a memory space 
attribute other than None and it is different than the forcing mem-
ory space attribute.  The optional forcing memory space attribute 
is useful to assign a memory space attribute to an expression that 
consists only of constants but is intended to refer to a fixed ad-
dress in a memory space.

The EQU directive is one of the directives that assigns a value 
other than the program counter to the label.  The label cannot be 
redefined anywhere else in the program (or section, if SECTION di-
rectives are being used).  The <expression> may be relative or ab-
solute, but cannot include a symbol that is not yet defined (no 
forward references are allowed).

See also:  SET

EXAMPLE:

A_D_PORT	EQU	X:$4000

This would assign the value $4000 with a memory space attribute of 
X to the symbol A_D_PORT.

COMPUTE	EQU	@LCV(L)

@LCV(L) is used to refer to the value and memory space attribute 
of the load location counter.  This value and memory space at-
tribute would be assigned to the symbol COMPUTE.

EXITM
Exit Macro

	EXITM

The EXITM directive will cause immediate termination of a macro 
expansion.  It is useful when used with the conditional assembly 
directive IF to terminate macro expansion when error conditions are 
detected.

A label is not allowed with this directive.

See also:  DUP, DUPA, DUPC, MACRO

EXAMPLE:

CALC	MACRO	XVAL,YVAL
	IF	XVAL<0
	FAIL	'Macro parameter value out of range'
	EXITM	; Exit macro
	ENDIF
	.
	.
	.
	ENDM

FAIL
Programmer Generated Error

	FAIL	
[{<str>|<exp>}[,{<str>|<exp>},...,{<str>|<exp>}]]

The FAIL directive will cause an error message to be output by the 
assembler.  The total error count will be incremented as with any 
other error.  The FAIL directive is normally used in conjunction 
with conditional assembly directives for exceptional condition 
checking.  The assembly proceeds normally after the error has been 
printed.  An arbitrary number of strings and expressions, in any 
order but separated by commas with no intervening white space, can 
be specified optionally to describe the nature of the generated 
error.

A label is not allowed with this directive.

See also:  MSG, WARN

EXAMPLE:

	FAIL	'Parameter out of range'

FORCE
Set Operand Forcing Mode

	FORCE	{SHORT | LONG | NONE}

The FORCE directive causes the assembler to force all immediate, 
memory, and address operands to the specified mode as if an explic-
it forcing operator were used.  Note that if a relocatable operand 
value forced short is determined to be too large for the instruc-
tion word, an error will occur at link time, not during assembly.  
Explicit forcing operators override the effect of this directive.

A label is not allowed with this directive.

See also:  <, >, #<, #>

EXAMPLE:

	FORCE	SHORT	; force operands short

GLOBAL
Global Section Symbol Declaration

	GLOBAL	  <symbol>[,<symbol>,...,<symbol>]

The GLOBAL directive is used to specify that the list of symbols 
is defined within the current section, and that those definitions 
should be accessible by all sections.  This directive is only valid 
if used within a program block bounded by the SECTION and ENDSEC 
directives.  If the symbols that appear in the operand field are 
not defined in the section, an error will be generated.

A label is not allowed with this directive.

See also:  SECTION, XDEF, XREF

EXAMPLE:

	SECTION	IO
	GLOBAL	LOOPA	; LOOPA will be globally accessible by 
other sections
	.
	.
	.
	ENDSEC

GSET
Set Global Symbol to a Value

<label>	GSET	<expression>

	GSET	<label>	<expression>

The GSET directive is used to assign the value of the expression 
in the operand field to the label. The GSET directive functions 
somewhat like the EQU directive. However, labels defined via the 
GSET directive can have their values redefined in another part of 
the program (but only through the use of another GSET or SET di-
rective). The GSET directive is useful for resetting a global SET 
symbol within a section, where the SET symbol would otherwise be 
considered local. The expression in the operand field of a GSET 
must be absolute and cannot include a symbol that is not yet defined 
(no forward references are allowed).

See also: EQU, SET

EXAMPLE:

COUNT	GSET	0	; INITIALIZE COUNT

HIMEM
Set High Memory Bounds

	HIMEM	<mem>[<rl>]:<expression>[,...]

The HIMEM directive establishes an absolute high memory bound for 
code and data generation. <mem> corresponds to one of the DSP mem-
ory spaces (X, Y, L, P, E). <rl> is one of the letters R for runtime 
counter or L for load counter. The <expression> is an absolute in-
teger value within the address range of the machine. If during as-
sembly the specified location counter exceeds the value given by 
<expression>, a warning is issued.

A label is not allowed with this directive.

See also:  LOMEM

EXAMPLE:

HIMEM		XR:$7FFF,YR:$7FFF				; SET X/Y RUN HIGH MEM BOUNDS

IDENT
Object Code Identification Record

[<label>]	IDENT	 <expression1>,<expression2>

The IDENT directive is used to create an identification record for 
the object module.  If <label> is specified, it will be used as the 
module name.  If <label> is not specified, then the filename of the 
source input file is used as the module name.  <expression1> is the 
version number; <expression2> is the revision number.  The two ex-
pressions must each evaluate to an integer result.  The comment 
field of the IDENT directive will also be passed on to the object 
module.

See also:  COBJ

EXAMPLE:

If the following line was included in the source file,

FFILTER	IDENT	1,2	; FIR FILTER MODULE

then the object module identification record would include the  
module name (FFILTER), the version number (1), the revision number 
(2), and the comment field (; FIR FILTER MODULE).

IF
Conditional Assembly Directive

	IF	<expression>
	.
	.
	[ELSE]	(the ELSE directive is optional)
	.
	.
	ENDIF

 Part of a program that is to be conditionally assembled must be 
bounded by an IF-ENDIF directive pair.  If the optional ELSE di-
rective is not present, then the source statements following the 
IF directive and up to the next ENDIF directive will be included 
as part of the source file being assembled only if the <expression> 
has a nonzero result.  If the <expression> has a value of zero, the 
source file will be assembled as if those statements between the 
IF and the ENDIF directives were never encountered.  If the ELSE 
directive is present and <expression> has a nonzero result, then 
the statements between the IF and ELSE directives will be assem-
bled, and the statements between the ELSE and ENDIF directives will 
be skipped.  Alternatively, if <expression> has a value of zero, 
then the statements between the IF and ELSE directives will be 
skipped, and the statements between the ELSE and ENDIF directives 
will be assembled.

The <expression> must have an absolute integer result and is con-
sidered true if it has a nonzero result.  The <expression> is false 
only if it has a result of 0.  Because of the nature of the direc-
tive, <expression> must be known on pass one (no forward references 
allowed).  IF directives can be nested to any level.  The ELSE di-
rective will always refer to the nearest previous IF directive as 
will the ENDIF directive.

A label is not allowed with this directive.

See also:  ENDIF

EXAMPLE:

	IF	@LST>0
	DUP	@LST	; Unwind LIST directive stack
	NOLIST
	ENDM
	ENDIF

INCLUDE
Include Secondary File

	INCLUDE	<string>  |  <<string>>

This directive is inserted into the source program at any point 
where a secondary file is to be included in the source input stream.  
The string specifies the filename of the secondary file.  The file-
name must be compatible with the operating system and can include 
a directory specification.  If no extension is given for the file-
name, a default extension of .ASM is supplied.

The file is searched for first in the current directory, unless the 
<<string>> syntax is used, or in the directory specified in 
<string>. If the file is not found, and the -I option was used on 
the command line that invoked the assembler, then the string spec-
ified with the -I option is prefixed to <string> and that directory 
is searched. If the <<string>> syntax is given, the file is 
searched for only in the directories specified with the -I option. 
Refer to Chapter 1, RUNNING THE ASSEMBLER.

A label is not allowed with this directive.

See also:  MACLIB

EXAMPLE:

	INCLUDE  'headers/io.asm'		; Unix example

	INCLUDE  'storage\mem.asm'		; MS-DOS example

	INCLUDE  <data.asm>		; Do not look in current di-
rectory

LIST
List the Assembly

	LIST

Print the listing from this point on.  The LIST directive will not 
be printed, but the subsequent source lines will be output to the 
source listing.  The default is to print the source listing.  If 
the IL option has been specified, the LIST directive has no effect 
when encountered within the source program.

The LIST directive actually increments a counter that is checked 
for a positive value and is symmetrical with respect to the NOLIST 
directive.  Note the following sequence:

	; Counter value currently 1
	LIST		; Counter value = 2
	LIST		; Counter value = 3
	NOLIST		; Counter value = 2
	NOLIST		; Counter value = 1

The listing still would not be disabled until another  NOLIST di-
rective was issued.

A label is not allowed with this directive.

See also:  NOLIST, OPT

EXAMPLE:

	IF	LISTON
	LIST		; Turn the listing back on
	ENDIF

LOCAL
Local Section Symbol Declaration

	LOCAL	  <symbol>[,<symbol>,...,<symbol>]

The LOCAL directive is used to specify that the list of symbols is 
defined within the current section, and that those definitions are 
explicitly local to that section.  It is useful in cases where a 
symbol is used as a forward reference in a nested section where the 
enclosing section contains a like-named symbol.  This directive is 
only valid if used within a program block bounded by the SECTION 
and ENDSEC directives.  The LOCAL directive must appear before 
<symbol> is defined in the section.  If the symbols that appear in 
the operand field are not defined in the section, an error will be 
generated.

A label is not allowed with this directive.

See also:  SECTION, XDEF, XREF

EXAMPLE:

	SECTION	IO
	LOCAL	LOOPA	; LOOPA local to this section
	.
	.
	.
	ENDSEC

LOMEM
Set Low Memory Bounds

	LOMEM	<mem>[<rl>]:<expression>[,...]

The LOMEM directive establishes an absolute low memory bound for 
code and data generation. <mem> corresponds to one of the DSP mem-
ory spaces (X, Y, L, P, E). <rl> is one of the letters R for runtime 
counter or L for load counter. The <expression> is an absolute in-
teger value within the address range of the machine. If during as-
sembly the specified location counter falls below the value given 
by <expression>, a warning is issued.

A label is not allowed with this directive.

See also:  HIMEM

EXAMPLE:

LOMEM		XR:$100,YR:$100			; SET X/Y RUN LOW MEM BOUNDS

LSTCOL
Set Listing Field Widths

	LSTCOL  [<la-
bw>[,<opcw>[,<oprw>[,<opc2w>[,<opr2w>[,<xw>[,<yw>]]]]]]]

Sets the width of the output fields in the source listing.  Widths 
are specified in terms of column positions.  The starting position 
of any field is relative to its predecessor except for the label 
field, which always starts at the same position relative to page 
left margin, program counter value, and cycle count display.  The 
widths may be expressed as any positive absolute integer expres-
sion.  However, if the width is not adequate to accommodate the 
contents of a field, the text is separated from the next field by 
at least one space.

Any field for which the default is desired may be null.  A null 
field can be indicated by two adjacent commas with no intervening 
space or by omitting any trailing fields altogether.  If the LSTCOL 
directive is given with no arguments all field widths are reset to 
their default values.

A label is not allowed with this directive.

See also:  PAGE

EXAMPLE:

LSTCOL		40,,,,,20,20		; Reset label, X, and Y data field 
widths

MACLIB
Macro Library

	MACLIB	<pathname>

This directive is used to specify the <pathname> (as defined by the 
operating system) of a directory that contains macro definitions.  
Each macro definition must be in a separate file, and the file must 
be named the same as the macro with the extension .ASM added.  For 
example, BLOCKMV.ASM would be a file that contained the definition 
of the macro called BLOCKMV.

If the assembler encounters a directive in the operation field that 
is not contained in the directive or mnemonic tables, the directory 
specified by <pathname> will be searched for a file of the unknown 
name (with the .ASM extension added).  If such a file is found, the 
current source line will be saved, and the file will be opened for 
input as an INCLUDE file.  When the end of the file is encountered, 
the source line is restored and processing is resumed.  Because the 
source line is restored, the processed file must have a macro def-
inition of the unknown directive name, or else an error will result 
when the source line is restored and processed.  However, the pro-
cessed file is not limited to macro definitions, and can include 
any legal source code statements.

Multiple MACLIB directives may be given, in which case the assem-
bler will search each directory in the order in which it is encoun-
tered.

A label is not allowed with this directive.

See also:  INCLUDE

EXAMPLE:

	MACLIB  'macros\mymacs\'		; IBM PC example
	MACLIB  'fftlib/'		; UNIX example

MACRO
Macro Definition

<label>	MACRO	[<dummy argument list>]
	.
	.
	<macro definition statements>
	.
	.
	ENDM

The dummy argument list has the form:

[<dumarg>[,<dumarg>,...,<dumarg>]]

The required label is the symbol by which the macro will be called.  
If the macro is named the same as an existing assembler directive 
or mnemonic, a warning will be issued.  This warning can be avoided 
with the RDIRECT directive.

The definition of a macro consists of three parts: the header, 
which assigns a name to the macro and defines the dummy arguments; 
the body, which consists of prototype or skeleton source state-
ments; and the terminator.  The header is the MACRO directive, its 
label, and the dummy argument list.  The body contains the pattern 
of standard source statements.  The terminator is the ENDM direc-
tive.

The dummy arguments are symbolic names that the macro processor 
will replace with arguments when the macro is expanded (called).  
Each dummy argument must obey the same rules as symbol names.  Dummy 
argument names that are preceded by an underscore are not allowed.  
Within each of the three dummy argument fields, the dummy arguments 
are separated by commas.  The dummy argument fields are separated 
by one or more blanks.

Macro definitions may be nested but the nested macro will not be 
defined until the primary macro is expanded.

Chapter 5 contains a complete description of macros.

See also:  DUP, DUPA, DUPC, DUPF, ENDM

EXAMPLE:

SWAP_SYM	MACRO	REG1,REG2	;swap REG1,REG2 using X0 as temp
	MOVE	R\?REG1,X0
	MOVE	R\?REG2,R\?REG1
	MOVE	X0,R\?REG2
	ENDM

MODE
Change Relocation Mode

	MODE	<ABS[OLUTE] | REL[ATIVE]>

Causes the assembler to change to the designated operational mode.  
The MODE directive may be given at any time in the assembly source 
to alter the set of location counters used for section addressing.  
Code generated while in absolute  mode will be placed in memory at 
the location determined during assembly.  Relocatable code and data 
are based from the enclosing section start address.  The MODE di-
rective has no effect when the command line -A option is issued.  
See Chapter 4 for more information on modes, sections, and reloca-
tion.

A label is not allowed with this directive.

See also:  ORG

EXAMPLE:

	MODE	ABS	; Change to absolute mode

MSG
Programmer Generated Message

	MSG	  
[{<str>|<exp>}[,{<str>|<exp>},...,{<str>|<exp>}]]

The MSG directive will cause a message to be output by the assem-
bler.  The error and warning counts will not be affected.  The MSG 
directive is normally used in conjunction with conditional assembly 
directives for informational purposes.  The assembly proceeds nor-
mally after the message has been printed.  An arbitrary number of 
strings and expressions, in any order but separated by commas with 
no intervening white space, can be specified optionally to describe 
the nature of the message.

A label is not allowed with this directive.

See also:  FAIL, WARN

EXAMPLE:

	MSG	'Generating sine tables'

NOLIST
Stop Assembly Listing

	NOLIST

Do not print the listing from this point on (including the NOLIST 
directive).  Subsequent source lines will not be printed.

The NOLIST directive actually decrements a counter that is checked 
for a positive value and is symmetrical with respect to the LIST 
directive.  Note the following sequence:

	; Counter value currently 1
	LIST		; Counter value = 2
	LIST		; Counter value = 3
	NOLIST		; Counter value = 2
	NOLIST		; Counter value = 1

The listing still would not be disabled until another  NOLIST di-
rective was issued.

A label is not allowed with this directive.

See also:  LIST, OPT

EXAMPLE:

	IF	LISTOFF
	NOLIST		; Turn the listing off
	ENDIF

OPT
Assembler Options

	OPT	<option>[,<option>,...,<option>]	[<comment>]

The OPT directive is used to designate the assembler options.  As-
sembler options are given in the operand field of the source input 
file and are separated by commas.  Options also may be specified 
using the command line -O option (see Chapter 1).  All options have 
a default condition.  Some options are reset to their default con-
dition at the end of pass one.  Some are allowed to have the prefix 
NO attached to them, which then reverses their meaning.

Options can be grouped by function into five different types:

1.  Listing format control
2.  Reporting options
3.  Message control
4.  Symbol options
5.  Assembler operation

Listing Format Control

These options control the format of the listing file:

FC	- Fold trailing comments
FF	- Form feeds for page ejects
FM	- Format messages
PP	- Pretty print listing
RC	- Relative comment spacing

Reporting Options

These options control what is reported in the listing file:

CEX	- Print DC expansions
CL	- Print conditional assembly directives
CRE	- Print symbol cross-reference
DXL	- Expand DEFINE directive strings in listing
HDR	- Generate listing headers
IL	- Inhibit source listing
LOC	- Print local labels in cross-reference
MC	- Print macro calls
MD	- Print macro definitions
MEX	- Print macro expansions
MU	- Print memory utilization report
NL	- Print conditional assembly and section nest-
ing levels
S	- Print symbol table
U	- Print skipped conditional assembly lines

Message Control

These options control the types of assembler messages that are gen-
erated:

AE	- Check address expressions
MSW	- Warn on memory space incompatibilities
UR	- Flag unresolved references
W	- Display warning messages

Symbol Options

These options deal with the handling of symbols by the assembler:

DEX	- Expand DEFINE symbols within quoted strings
IC	- Ignore case in symbol names
NS	- Support symbol scoping in nested sections
SCL	- Scope structured control statement labels
SCO	- Structured control statement labels to list-
ing/object file
SO	- Write symbols to object file
XLL	- Write local labels to object file
XR	- Recognize XDEFed symbols without XREF

Assembler Operation

Miscellaneous options having to do with internal assembler opera-
tion:

CC	- Enable cycle counts
CK	- Enable checksumming
CM	- Preserve comment lines within macros
CONST	- Make EQU symbols assembly time constants
CONTCK	- Continue checksumming
DLD	- Do not restrict directives in loops
GL	- Make all section symbols global
GS	- Make all sections global static
INTR	- Perform interrupt location checks
LB	- Byte increment load counter
LDB	- Listing file debug
MI	- Scan MACLIB directories for include files
PS	- Pack strings
PSM	- Programmable short addressing mode
RP	- Generate NOP to accommodate pipeline delay
RSV	- Check reserve data memory locations
SI	- Interpret short immediate as long or sign ex-
tended
SVO	- Preserve object file on errors

Following are descriptions of the individual options.  The paren-
thetical inserts specify default if the option is the default con-
dition, and reset if the option is reset to its default state at 
the end of pass one.

A label is not allowed with this directive.

AE	(default, reset) Check address expressions for appropri-
ate arithmetic operations.  For example, this will check 
that only valid add or subtract operations are performed 
on address terms.

CC	Enable cycle counts and clear total cycle count.  Cycle 
counts will be shown on the output listing for each in-
struction.  Cycle counts assume a full instruction fetch 
pipeline and no wait states.

CEX	Print DC expansions.

CK	Enable checksumming of instruction and data values and 
clear cumulative checksum.  The checksum value can be ob-
tained using the @CHK() function (see Chapter 3).

CL	(default, reset) Print the conditional assembly direc-
tives.

CM	(default, reset) Preserve comment lines of macros when 
they are defined. Note that any comment line within a mac-
ro definition that starts with two consecutive semicolons 
(;;) is never preserved in the macro definition.

CONST	EQU symbols are maintained as assembly time constants and 
will not be sent to the object file.  This option, if used, 
must be specified before the first symbol in the source 
program is defined.

CONTC	Re-enable cycle counts.  Does not clear total cycle 
counts.  The cycle count for each instruction will be 
shown on the output listing.

CONTCK	Re-enable checksumming of instructions and data.  Does not 
clear cumulative checksum value.

CRE	Print a cross reference table at the end of the source 
listing.  This option, if used, must be specified before 
the first symbol in the source program is defined.

DEX	Expand DEFINE symbols within quoted strings.  Can also be 
done on a case-by-case basis using double-quoted strings.

DLD	Do not restrict directives in DO loops. The presence of 
some directives in DO loops does not make sense, including 
some OPT directive variations. This option suppresses er-
rors on particular directives in loops.

DXL	(default, reset) Expand DEFINE directive strings in list-
ing.

FC	Fold trailing comments.  Any trailing comments that are 
included in a source line will be folded underneath the 
source line and aligned with the opcode field.  Lines that 
start with the comment character will be aligned with the 
label field in the source listing.  The FC option is useful 
for displaying the source listing on 80 column devices.

FF	Use form feeds for page ejects in the listing file.

FM	Format assembler messages so that the message text is 
aligned and broken at word boundaries.

GL	Make all section symbols global.  This has the same effect 
as declaring every section explicitly GLOBAL.  This option 
must be given before any sections are defined explicitly 
in the source file.

GS	(default, reset in absolute mode) Make all sections global 
static.  All section counters and attributes will be as-
sociated with the GLOBAL section.  This option must be 
given before any sections are defined explicitly in the 
source file.

HDR	(default, reset) Generate listing header along with titles 
and subtitles.

IC	Ignore case in symbol, section, and macro names.  This di-
rective must be issued before any symbols, sections, or 
macros are defined.

IL	Inhibit source listing.  This option will stop the assem-
bler from producing a source listing.

INTR	(default, reset in absolute mode) Perform interrupt loca-
tion checks.  Certain DSP instructions may not appear in 
the interrupt vector locations in program memory.  This 
option enables the assembler to check for these instruc-
tions when the program counter is within the interrupt 
vector bounds.

LB	Increment load counter (if different from runtime) by num-
ber of bytes in DSP word to provide byte-wide support for 
overlays in bootstrap mode. This option must appear before 
any code or data generation.

LDB	Use the listing file as the debug source file rather than 
the assembly language file. The -L command line option to 
generate a listing file must be specified for this option 
to take effect.

LOC	Include local labels in the symbol table and cross-refer-
ence listing. Local labels are not normally included in 
these listings. If neither the S or CRE options are spec-
ified, then this option has no effect. The LOC option must 
be specified before the first symbol is encountered in the 
source file.

MC	(default, reset) Print macro calls.

MD	(default, reset) Print macro definitions.

MEX	Print macro expansions.

MI	Scan MACLIB directory paths for include files.  The as-
sembler ordinarily looks for included files only in the 
directory specified in the INCLUDE directory or in the 
paths given by the -I command line option.  If the MI op-
tion is used the assembler will also look for included 
files in any designated MACLIB directories.

MSW	(default, reset) Issue warning on memory space incompat-
ibilities.

MU	Include a memory utilization report in the source listing. 
This option must appear before any code or data genera-
tion.

NL	Display conditional assembly (IF-ELSE-ENDIF) and section 
nesting levels on listing.

NOAE	Do not check address expressions.

NOCC	(default, reset) Disable cycle counts.  Does not clear to-
tal cycle count.

NOCEX	(default, reset) Do not print DC expansions.

NOCK	(default, reset) Disable checksumming of instruction and 
data values.

NOCL	Do not print the conditional assembly directives.

NOCM	Do not preserve comment lines of macros when they are de-
fined.

NODEX	(default, reset) Do not expand DEFINE symbols within quot-
ed strings.

NODLD	(default, reset) Restrict use of certain directives in DO 
loop.

NODXL	Do not expand DEFINE directive strings in listing.

NOFC	(default, reset) Inhibit folded comments.

NOFF	(default, reset) Use multiple line feeds for page ejects 
in the listing file.

NOFM	(default, reset) Do not format assembler messages.

NOGS	(default, reset in relative mode) Do not make all sections 
global static.

NOHDR	Do not generate listing header.  This also turns off ti-
tles and subtitles.

NOINTR	(default, reset in relative mode) Do not perform interrupt 
location checks.

NOMC	Do not print macro calls.

NOMD	Do not print macro definitions.

NOMEX	(default, reset) Do not print macro expansions.

NOMI	(default, reset) Do not scan MACLIB directory paths for 
include files.

NOMSW	Do not issue warning on memory space incompatibilities.

NONL	(default, reset) Do not display nesting levels on listing.

NONS	Do not allow scoping of symbols within nested sections.

NOPP	Do not pretty print listing file.  Source lines are sent 
to the listing file as they are encountered in the source, 
with the exception that tabs are expanded to spaces and 
continuation lines are concatenated into a single physical 
line for printing.

NOPS	Do not pack strings in DC directive.  Individual bytes in 
strings will be stored one byte per word.

NORC	(default, reset) Do not space comments relatively.

NORP	(default, reset) Do not generate instructions to accommo-
date pipeline delay.

NOSCL	Do not maintain the current local label scope when a 
structured control statement label is encountered.

NOSI	(DSP56000 only) (default, reset) Interpret an eight-bit 
short immediate value moved to a fractional register as a 
short unless forced long.

NOU	(default, reset) Do not print the lines excluded from the 
assembly due to a conditional assembly directive.

NOUR	(default, reset) Do not flag unresolved external refer-
ences.

NOW	Do not print warning messages.

NS	(default, reset) Allow scoping of symbols within nested 
sections.

PP	(default, reset) Pretty print listing file.  The assembler 
attempts to align fields at a consistent column position 
without regard to source file formatting.

PS	(default, reset) Pack strings in DC directive.  Individual 
bytes in strings will be packed into consecutive target 
words for the length of the string.

RC	Space comments relatively in listing fields.  By default, 
the assembler always places comments at a consistent col-
umn position in the listing file.  This option allows the 
comment field to float:  on a line containing only a label 
and opcode, the comment would begin in the operand field.

RP	Generate NOP instructions to accommodate pipeline delay.  
If an address register is loaded in one instruction then 
the contents of the register is not available for use as 
a pointer until after the next instruction.  Ordinarily 
when the assembler detects this condition it issues an er-
ror message.  The RP option will cause the assembler to 
output a NOP instruction into the output stream instead 
of issuing an error.

S	Print symbol table at the end of the source listing.  This 
option has no effect if the CRE option is used.

SCL	(default, reset) Structured control statements generate 
non-local labels that ordinarily are not visible to the 
programmer. This can create problems when local labels are 
interspersed among structured control statements. This 
option causes the assembler to maintain the current local 
label scope when a structured control statement label is 
encountered.

SCO	Send structured control statement labels to object and 
listing files. Normally the assembler does not externalize 
these labels. This option must appear before any symbol 
definition.

SI	(DSP56000 only) Interpret an eight-bit short immediate 
value moved to a fractional register as a long unless 
forced short.

SO	Write symbol information to object file. This option is 
recognized but performs no operation in COFF assemblers.

SVO	Preserve object file on errors. Normally any object file 
produced by the assembler is deleted if errors occur dur-
ing assembly. This option must be given before any code 
or data is generated.

U	Print the unassembled lines skipped due to failure to sat-
isfy the condition of a conditional assembly directive.

UR	Generate a warning at assembly time for each unresolved 
external reference.  This option works only in relocatable 
mode.

W	(default, reset) Print all warning messages.

WEX	Add warning count to exit status.  Ordinarily the assem-
bler exits with a count of errors.  This option causes the 
count of warnings to be added to the error count.

XLL	Write underscore local labels to object file.  This is 
primarily used to aid debugging.  This option, if used, 
must be specified before the first symbol in the source 
program is defined.

XR	Causes XDEFed symbols to be recognized within other sec-
tions without being XREFed.  This option, if used, must 
be specified before the first symbol in the source program 
is encountered.

EXAMPLE:

	OPT	CEX,MEX	; Turn on DC and macro expansions
	OPT	CRE,MU	; Cross reference, memory utili-
zation

ORG
Initialize Memory Space and Location Counters

        ORG		
<rms>[<rlc>][<rmp>]:[<exp1>][,<lms>[<llc>][<lmp>]:[<exp2>]]

        ORG 		
<rms>[<rmp>][(<rce>)]:[<exp1>][,<lms>[<lmp>][(<lce>)]:[<exp2
>]]

The ORG directive is used to specify addresses and to indicate mem-
ory space and mapping changes.  It also can designate an implicit 
counter mode switch in the assembler and serves as a mechanism for 
initiating overlays.

A label is not allowed with this directive.

<rms>

Which memory space (X, Y, L, P, or E) will be used as the 
runtime memory space. If the memory space is L, any al-
located datum with a value greater than the target word 
size will be extended to two words; otherwise, it is 
truncated. If the memory space is E, then depending on 
the memory space qualifier, any generated words will be 
split into bytes, one byte per word, or a 16/8-bit com-
bination.

<rlc>

Which runtime counter H, L, or default (if neither H or 
L is specified), that is associated with the <rms> will 
be used as the runtime location counter.

<rmp>

Indicates the runtime physical mapping to DSP memory:  I 
- internal, E - external, R - ROM, A - port A, B - port 
B.  If not present, no explicit mapping is done.

<rce>

Non-negative absolute integer expression representing 
the counter number to be used as the runtime location 
counter.  Must be enclosed in parentheses.  Should not 
exceed the value 65535.

<exp1>

Initial value to assign to the runtime counter used as 
the <rlc>. If <exp1> is a relative expression the assem-
bler uses the relative location counter. If <exp1> is an 
absolute expression the assembler uses the absolute lo-
cation counter. If <exp1> is not specified, then the last 
value and mode that the counter had will be used.

<lms>

Which memory space (X, Y, L, P, or E) will be used as the 
load memory space. If the memory space is L, any allo-
cated datum with a value greater than the target word 
size will be extended to two words; otherwise, it is 
truncated. If the memory space is E, then depending on 
the memory space qualifier, any generated words will be 
split into bytes, one byte per word, or a 16/8-bit com-
bination.

<llc>

Which load counter, H, L, or default (if neither H or L 
is specified), that is associated with the <lms> will be 
used as the load location counter.

<lmp>

Indicates the load physical mapping to DSP memory:  I - 
internal, E - external, R - ROM, A - port A, B - port B.  
If not present, no explicit mapping is done.

<lce>

Non-negative absolute integer expression representing 
the counter number to be used as the load location 
counter.  Must be enclosed in parentheses.  Should not 
exceed the value 65535.

<exp2>

Initial value to assign to the load counter used as the 
<llc>.  If <exp2>  is a relative expression the assembler 
uses the relative location counter.  If <exp2>  is an 
absolute expression the assembler uses the absolute  lo-
cation counter.  If <exp2> is not specified, then the 
last value and mode that the counter had will be used.

If the last half of the operand field in an ORG directive dealing 
with the load memory space and counter is not specified, then the 
assembler will assume that the load memory space and load location 
counter are the same as the runtime memory space and runtime loca-
tion counter.  In this case, object code is being assembled to be 
loaded into the address and memory space where it will be when the 
program is run, and is not an overlay.

If the load memory space and counter are given in the operand field, 
then the assembler always generates code for an overlay. Whether 
the overlay is absolute or relocatable depends upon the current 
operating mode of the assembler and whether the load counter value 
is an absolute or relative expression. If the assembler is running 
in absolute mode, or if the load counter expression is absolute, 
then the overlay is absolute. If the assembler is in relative mode 
and the load counter expression is relative, the overlay is relo-
catable. Runtime relocatable overlay code is addressed relative to 
the location given in the runtime location counter expression. This 
expression, if relative, may not refer to another overlay block.

See also:  MODE

EXAMPLES:

ORG  P:$1000

Sets the  runtime memory space to P.  Selects the default runt-
ime counter (counter 0) associated with P space to use as the 
runtime location counter and initializes it to $1000.  The 
load memory space is implied to be P, and the load location 
counter is assumed to be the same as the runtime location 
counter.

ORG  PHE:

Sets the runtime memory space to P.  Selects the H load counter 
(counter 2) associated with P space to use as the runtime lo-
cation counter.  The H counter will not be initialized, and 
its last value will be used.  Code generated hereafter will 
be mapped to external (E) memory.  The load memory space is 
implied  to be P, and the load location counter is assumed to 
be the same as the runtime location counter.

ORG  PI:OVL1,Y:

Indicates code will be generated for an overlay. The runtime 
memory space is P, and the default counter is used as the runt-
ime location counter. It will be reset to the value of OVL1. 
If the assembler is in absolute mode via the -A command line 
option then OVL1 must be an absolute expression. If OVL1 is 
an absolute expression the assembler uses the absolute runtime 
location counter. If OVL1 is a relocatable value the assembler 
uses the relative runtime location counter. In this case OVL1 
must not itself be an overlay symbol (e.g. defined within an 
overlay block). The load memory space is Y. Since neither H, 
L, nor any counter expression was specified as the load 
counter, the default load counter (counter 0) will be used as 
the load location counter. The counter value and mode will be 
whatever it was the last time it was referenced.

ORG  XL:,E8:

Sets the runtime memory space to X. Selects the L counter 
(counter 1) associated with X space to use as the runtime lo-
cation counter. The L counter will not be initialized, and its 
last value will be used. The load memory space is set to E, 
and the qualifier 8 indicates a bytewise RAM configuration. 
Instructions and data will be generated eight bits per output 
word with byte-oriented load addresses. The default load 
counter will be used and there is no explicit load origin.

ORG  P(5):,Y:$8000

Indicates code will be generated for an absolute overlay.  The 
runtime memory space is P, and the counter used as the runtime 
location counter is counter 5.  It will not be initialized, 
and the last previous value of counter 5 will be used.  The 
load memory space is Y.  Since neither H, L, nor any counter 
expression was specified as the load counter, the default load 
counter (counter 0) will be used as the load location counter.  
The default load counter will be initialized to $8000.

PAGE
Top of Page/Size Page

	PAGE	  [<exp1>[,<exp2>...,<exp5>]]

The PAGE directive has two forms:

1.	If no arguments are supplied, then the assembler will advance 
the listing to the top of the next page.  In this case, the 
PAGE directive will not be output.

2.	The PAGE directive with arguments can be used to specify the 
printed format of the output listing.  Arguments may be any 
positive absolute integer expression.  The arguments in the 
operand field (as explained below) are separated by commas.  
Any argument can be left as the default or last set value by 
omitting the argument and using two adjacent commas.  The PAGE 
directive with arguments will not cause a page eject and will 
be printed in the source listing.

A label is not allowed with this directive.

The arguments in order are:

PAGE_WIDTH		<exp1>

Page width in terms of number of output columns per line (de-
fault 80, min 1, max 255).

PAGE_LENGTH		<exp2>

Page length in terms of total number of lines per page (de-
fault 66, min 10, max 255).  As a special case a page length 
of 0 (zero) turns off all headers, titles, subtitles, and page 
breaks.

BLANK_TOP		<exp3>

Blank lines at top of page.  (default 0, min 0, max see below).

BLANK_BOTTOM		<exp4>

Blank lines at bottom of page.  (default 0, min 0, max see 
below).

BLANK_LEFT		<exp5>

Blank left margin.  Number of blank columns at the left of the 
page.  (default 0, min 0, max see below).

The following relationships must be maintained:

BLANK_TOP + BLANK_BOTTOM <= PAGE_LENGTH - 10

BLANK_LEFT < PAGE_WIDTH

See also:  LSTCOL

EXAMPLE:

	PAGE	132,,3,3	; Set width to132, 3 line top/bottom 
margins
	PAGE		; Page eject

PMACRO
Purge Macro Definition

	PMACRO	<symbol>[,<symbol>,...,<symbol>]

The specified macro definition will be purged from the macro table, 
allowing the macro table space to be reclaimed.

A label is not allowed with this directive.

See also:  MACRO

EXAMPLE:

	PMACRO 	MAC1,MAC2

This statement would cause the macros named MAC1 and MAC2 to be 
purged.

PRCTL
Send Control String to Printer

	PRCTL	<exp>I<string>,...,<exp>I<string>

PRCTL simply concatenates its arguments and ships them to the list-
ing file (the directive line itself is not printed unless there is 
an error).  <exp> is a byte expression and <string> is an assembler 
string.  A byte expression would be used to encode non-printing 
control characters, such as ESC.  The string may be of arbitrary 
length, up to the maximum assembler-defined limits.

PRCTL may appear anywhere in the source file and the control string 
will be output at the corresponding place in the listing file.  How-
ever, if a PRCTL directive is the last line in the last input file 
to be processed, the assembler insures that all error summaries, 
symbol tables, and cross-references have been printed before send-
ing out the control string.  This is so a PRCTL directive can be 
used to restore a printer to a previous mode after printing is done.  
Similarly, if the PRCTL directive appears as the first line in the 
first input file, the control string will be output before page 
headings or titles.

The PRCTL directive only works if the -L command line option is 
given; otherwise it is ignored.  See Chapter 1 for more information 
on the -L option.

A label is not allowed with this directive.

EXAMPLE:

	PRCTL	$1B,'E'	; Reset HP LaserJet print-
er

RADIX
Change Input Radix for Constants

	RADIX	<expression>

Changes the input base of constants to the result of <expression>.  
The absolute integer expression must evaluate to one of the legal 
constant bases (2, 10, or 16).  The default radix is 10.  The RADIX 
directive allows the programmer to specify constants in a preferred 
radix without a leading radix indicator.  The radix prefix for base 
10 numbers is the grave accent (`).  Note that if a constant is 
used to alter the radix, it must be in the appropriate input base 
at the time the RADIX directive is encountered.

A label is not allowed with this directive.

EXAMPLE:

_RAD10	DC	10	; Evaluates to hex A
	RADIX	2
_RAD2	DC	10	; Evaluates to hex 2
	RADIX	`16
_RAD16	DC	10	; Evaluates to hex 10
	RADIX	3	; Bad radix expression

RDIRECT
Remove Directive or Mnemonic from Table

	RDIRECT	<direc>[,<direc>,...,<direc>]

The RDIRECT directive is used to remove directives from the assem-
bler directive and mnemonic tables.  If the directive or mnemonic 
that has been removed is later encountered in the source file, it 
will be assumed to be a macro.  Macro definitions that have the 
same name as assembler directives or mnemonics will cause a warning 
message to be output unless the RDIRECT directive has been used to 
remove the directive or mnemonic name from the assembler's tables.  
Additionally, if a macro is defined through the MACLIB directive 
which has the same name as an existing directive or opcode, it will 
not automatically replace that directive or opcode as previously 
described.  In this case, the RDIRECT directive must be used to 
force the replacement.

Since the effect of this directive is global, it cannot be used in 
an explicitly-defined section (see SECTION directive).  An error 
will result if the RDIRECT directive is encountered in a section.

A label is not allowed with this directive.

EXAMPLE:

	RDIRECT	PAGE,MOVE

This would cause the assembler to remove the PAGE directive from 
the directive table and the MOVE mnemonic from the mnemonic table.

SCSJMP
Set Structured Control Statement Branching Mode

	SCSJMP	{SHORT | LONG | NONE}

The SCSJMP directive is analogous to the FORCE directive, but it 
only applies to branches generated automatically by structured con-
trol statements (see Chapter 7).  There is no explicit way, as with 
a forcing operator, to force a branch short or long when it is pro-
duced by a structured control statement.  This directive will cause 
all branches resulting from subsequent structured control state-
ments to be forced to the specified mode.

Just like the FORCE pseudo-op, errors can result if a value is too 
large to be forced short.  For relocatable code, the error may not 
occur until the linking phase.

See also:  FORCE, SCSREG

A label is not allowed with this directive.

EXAMPLE:

	SCSJMP	SHORT	; force all subsequent SCS jumps 
short

SCSREG
Reassign Structured Control Statement Registers

	SCSREG	[<srcreg>[,<dstreg>[,<tmpreg>[,<extreg>]]]]

The SCSREG directive reassigns the registers used by structured 
control statement (SCS) directives (see Chapter 7).  It is conve-
nient for reclaiming default SCS registers when they are needed as 
application operands within a structured control construct.  <sr-
creg> is ordinarily the source register for SCS data moves.  
<dstreg> is the destination register.  <tmpreg> is a temporary reg-
ister for swapping SCS operands.  <extreg> is an extra register for 
complex SCS operations.  With no arguments SCSREG resets the SCS 
registers to their default assignments.

The SCSREG directive should be used judiciously to avoid register 
context errors during SCS expansion.  Source and destination reg-
isters may not necessarily be used strictly as source and destina-
tion operands.  The assembler does no checking of reassigned reg-
isters beyond validity for the target processor.  Errors can result 
when a structured control statement is expanded and an improper 
register reassignment has occurred.  It is recommended that the MEX 
option (see the OPT directive) be used to examine structured con-
trol statement expansion for relevant constructs to determine de-
fault register usage and applicable reassignment strategies.

See also:  OPT (MEX), SCSJMP

A label is not allowed with this directive.

EXAMPLE:

	SCSREG	Y0,B	; reassign SCS source and dest. 
registers

SECTION
Start Section

	SECTION	<symbol>	[GLOBAL | STATIC | LOCAL]
	.
	.
	<section source statements>
	.
	.
	ENDSEC

The SECTION directive defines the start of a section.  All symbols 
that are defined within a section have the <symbol> associated with 
them as their section name.  This serves to protect them from like-
named symbols elsewhere in the program.  By default, a symbol de-
fined inside any given section is private to that section unless 
the GLOBAL or LOCAL qualifier accompanies the SECTION directive.

Any code or data inside a section is considered an indivisible 
block with respect to relocation.  Code or data associated with a 
section is independently relocatable within the memory space to 
which it is bound, unless the STATIC qualifier follows the SECTION 
directive on the instruction line.

Symbols within a section are generally distinct from other symbols 
used elsewhere in the source program, even if the symbol name is 
the same.  This is true as long as the section name associated with 
each symbol is unique, the symbol is not declared public (XDEF/
GLOBAL), and the GLOBAL or LOCAL qualifier is not used in the sec-
tion declaration.  Symbols that are defined outside of a section 
are considered global symbols and have no explicit section name 
associated with them.  Global symbols may be referenced freely from 
inside or outside of any section, as long as the global symbol name 
does not conflict with another symbol by the same name in a given 
section.

If the GLOBAL qualifier follows the <section name> in the SECTION 
directive, then all symbols defined in the section until the next 
ENDSEC directive are considered global.  The effect is as if every 
symbol in the section were declared with GLOBAL.  This is useful 
when a section needs to be independently relocatable, but data hid-
ing is not desired.

If the STATIC qualifier follows the <section name> in the SECTION 
directive, then all code and data defined in the section until the 
next ENDSEC directive are relocated in terms of       the immedi-
ately enclosing section. The effect with respect to relocation is 
as if all code and data in the section were defined within the par-
ent section. This is useful when a section needs data hiding, but 
independent relocation is not required.

If the LOCAL qualifier follows the <section name> in the SECTION 
directive, then all symbols defined in the section until the next 
ENDSEC directive are visible to the immediately enclosing section.  
The effect is as if every symbol in the section were defined within 
the parent section.  This is useful when a section needs to be in-
dependently relocatable, but data hiding within an enclosing sec-
tion is not required.

The division of a program into sections controls not only labels 
and symbols, but also macros and DEFINE directive symbols.  Macros 
defined within a section are private to that section and are dis-
tinct from macros defined in other sections even if they have the 
same macro name.  Macros defined outside of sections are considered 
global and may be used within any section.  Similarly, DEFINE di-
rective symbols defined within a section are private to that sec-
tion and DEFINE directive symbols defined outside of any section 
are globally applied.  There are no directives that correspond to 
XDEF for macros or DEFINE symbols, and therefore, macros and DEFINE 
symbols defined in a section can never be accessed globally.  If 
global accessibility is desired, the macros and DEFINE symbols 
should be defined outside of any section.

Sections can be nested to any level.  When the assembler encounters 
a nested section, the current section is stacked and the new sec-
tion is used.  When the ENDSEC directive of the nested section is 
encountered, the assembler restores the old section and uses it.  
The ENDSEC directive always applies to the most previous SECTION 
directive.  Nesting sections provides a measure of scoping for sym-
bol names, in that symbols defined within a given section are vis-
ible to other sections nested within it.  For example, if section 
B is nested inside section A, then a symbol defined in section A 
can be used in section B without XDEFing in section A or XREFing 
in section B.  This scoping behavior can be turned off and on with 
the NONS and NS options respectively (see the OPT directive, this 
chapter).

Sections may also be split into separate parts.  That is, <section 
name> can be used multiple times with SECTION and ENDSEC directive 
pairs.  If this occurs, then these separate (but identically named) 
sections can access each others symbols freely without the use of 
the XREF and XDEF directives.  If the XDEF and XREF directives are 
used within one section, they apply to all sections with the same 
section name.  The reuse of the section name is allowed to permit 
the program source to be arranged in an arbitrary manner (for ex-
ample, all statements that reserve X space storage locations 
grouped together), but retain the privacy of the symbols for each 
section.

When the assembler operates in relative mode (the default), sec-
tions act as the basic grouping for relocation of code and data 
blocks.  For every section defined in the source a set of location 
counters is allocated for each DSP memory space.  These counters 
are used to maintain offsets of data and instructions relative to 
the beginning of the section.  At link time sections can be relo-
cated to an absolute address, loaded in a particular order, or 
linked contiguously as specified by the programmer.  Sections which 
are split into parts or among files are logically recombined so 
that each section can be relocated as a unit.

Sections may be relocatable or absolute.  In the assembler absolute 
mode (command line -A option) all sections are considered absolute.  
A full set of locations counters is reserved for each absolute sec-
tion unless the GS option is given (see the OPT directive, this 
chapter).  In relative mode, all sections are initially relocat-
able.  However, a section or a part of a section may be made abso-
lute either implicitly by using the ORG directive, or explicitly 
through use of the MODE directive.

A label is not allowed with this directive.

See also:  MODE, ORG, GLOBAL, LOCAL, XDEF, XREF

EXAMPLE:

	SECTION	TABLES	; TABLES will be the section name

SET
Set Symbol to a Value

<label>	SET	<expression>

	SET	<label>	<expression>

The SET directive is used to assign the value of the expression in 
the operand field to the label.  The SET directive functions some-
what like the EQU directive.  However, labels defined via the SET 
directive can have their values redefined in another part of the 
program (but only through the use of another SET directive).  The 
SET directive is useful in establishing temporary or reusable 
counters within macros.  The expression in the operand field of a 
SET must be absolute and cannot include a symbol that is not yet 
defined (no forward references are allowed).

See also: EQU, GSET

EXAMPLE:

COUNT	SET	0	; INITIALIZE COUNT

STITLE
Initialize Program Sub-Title

	STITLE	[<string>]

The STITLE directive initializes the program subtitle to the string 
in the operand field.  The subtitle will be printed on the top of 
all succeeding pages until another STITLE directive is encountered.  
The subtitle is initially blank.  The STITLE directive will not be 
printed in the source listing.  An STITLE directive with no string 
argument will cause the current subtitle to be blank.

A label is not allowed with this directive.

See also:  TITLE

EXAMPLE:

	STITLE	'COLLECT SAMPLES'

SYMOBJ
Write Symbol Information to Object File

	SYMOBJ	<symbol>[,<symbol>,...,<symbol>]

The SYMOBJ directive causes information for each <symbol> to be 
written to the object file.  This directive is recognized but cur-
rently performs no operation in COFF assemblers (see Appendix E, 
MOTOROLA DSP OBJECT FILE FORMAT (COFF)).

A label is not allowed with this directive.

EXAMPLE:

	SYMOBJ	XSTART,HIRTN,ERRPROC

TABS
Set Listing Tab Stops

	TABS	<tabstops>

The TABS directive allows resetting the listing file tab stops from 
the default value of 8.

A label is not allowed with this directive.

See also:  LSTCOL

EXAMPLE:

	TABS	4	; Set listing file tab stops to 4

TITLE
Initialize Program Title

	TITLE	[<string>]

The TITLE directive initializes the program title to the string in 
the operand field.  The program title will be printed on the top 
of all succeeding pages until another TITLE directive is encoun-
tered.  The title is initially blank.  The TITLE directive will not 
be printed in the source listing.  A TITLE directive with no string 
argument will cause the current title to be blank.

A label is not allowed with this directive.

See also:  STITLE

EXAMPLE:

	TITLE	'FIR FILTER'

UNDEF
Undefine DEFINE Symbol

	UNDEF	[<symbol>]

The UNDEF directive causes the substitution string associated with 
<symbol> to be released, and <symbol> will no longer represent a 
valid DEFINE substitution.  See the DEFINE directive for more in-
formation.

A label is not allowed with this directive.

See also:  DEFINE

EXAMPLE:

	UNDEF	DEBUG	; UNDEFINES THE DEBUG SUBSTITUTION STRING

WARN
Programmer Generated Warning

	WARN	
[{<str>|<exp>}[,{<str>|<exp>},...,{<str>|<exp>}]]

The WARN directive will cause a warning message to be output by the 
assembler.  The total warning count will be incremented as with any 
other warning.  The WARN directive is normally used in conjunction 
with conditional assembly directives for exceptional condition 
checking.  The assembly proceeds normally after the warning has 
been printed.   An arbitrary number of strings and expressions, in 
any order but separated by commas with no intervening white space, 
can be specified optionally to describe the nature of the generated 
warning.

A label is not allowed with this directive.

See also:  FAIL, MSG

EXAMPLE:

	WARN	'parameter too large'

XDEF
External Section Symbol Definition

	XDEF	  <symbol>[,<symbol>,...,<symbol>]

The XDEF directive is used to specify that the list of symbols is 
defined within the current section, and that those definitions 
should be accessible by sections with a corresponding XREF direc-
tive.  This directive is only valid if used within a program section 
bounded by the SECTION and ENDSEC directives.  The XDEF directive 
must appear before <symbol> is defined in the section.  If the sym-
bols that appear in the operand field are not defined in the sec-
tion, an error will be generated.

A label is not allowed with this directive.

See also:  SECTION, XREF

EXAMPLE:

	SECTION	IO
	XDEF	LOOPA	; LOOPA will be  accessible by sections 
with XREF
	.
	.
	.
	ENDSEC

XREF
External Section Symbol Reference

	XREF	  <symbol>[,<symbol>,...,<symbol>]

The XREF directive is used to specify that the list of symbols is 
referenced in the current section, but is not defined within the 
current section.  These symbols must either have been defined out-
side of any section or declared as globally accessible within an-
other section using the XDEF directive.  If the XREF directive is 
not used to specify that a symbol is defined globally and the symbol 
is not defined within the current section, an error will be gener-
ated, and all references within the current section to such a sym-
bol will be flagged as undefined.  The XREF directive must appear 
before any reference to <symbol> in the section.

A label is not allowed with this directive.

See also:  SECTION, XDEF

EXAMPLE:

	SECTION	FILTER
	XREF	AA,CC,DD	; XDEFed symbols within section
	.
	.
	.
	ENDSEC


Chapter 7

STRUCTURED CONTROL STATEMENTS

7.1	  INTRODUCTION

An assembly language provides an instruction set for performing 
certain rudimentary operations.  These operations in turn may be 
combined into control structures such as loops (FOR, REPEAT, WHILE) 
or conditional branches (IF-THEN, IF-THEN-ELSE).  The assembler, 
however, accepts formal, high-level directives that specify these 
control structures, generating the appropriate assembly language 
instructions for their efficient implementation.  This use of 
structured control statement directives improves the readability 
of assembly language programs, without compromising the desirable 
aspects of programming in an assembly language.

7.2	  STRUCTURED CONTROL DIRECTIVES

The following directives are used for structured control.  Note the 
leading period, which distinguishes these keywords from other di-
rectives and mnemonics.  Structured control directives may be spec-
ified in either upper or lower case, but they must appear in the 
opcode field  of the instruction line (e.g.  they must be preceded 
either by a label, a space, or a tab).

.BREAK	.ENDI	.LOOP
.CONTINUE	.ENDL	.REPEAT
.ELSE	.ENDW	.UNTIL
.ENDF	.FOR	.WHILE
	.IF

In addition, the following keywords are used in structured control 
statements:

AND	DOWNTO	TO
BY	OR
DO	THEN

Note that AND, DO, and OR are reserved assembler instruction mne-
monics.

7.3	  SYNTAX

The formats for the .BREAK, .CONTINUE, .FOR, .IF, .LOOP, .REPEAT, 
and .WHILE statements are given in sections 7.3.4 through 7.3.2.  
Syntactic variables used in the formats are defined as follows:

<expression>	A simple or compound expression (section 7.4).

<stmtlist>	Zero or more assembler directives, structured 
control statements, or executable instructions.

Note than an assembler directive (Chapter 6) occurring within 
a structured control statement is examined exactly once -- at 
assembly time.  Thus the presence of a directive within a 
.FOR, .LOOP, .REPEAT, or .WHILE statement does not imply re-
peated occurrence of an assembler directive; nor does the 
presence of a directive within an .IF-THEN-.ELSE structured 
control statement imply conditional assembly.

<op1>	A user-defined operand whose register/memory lo-
cation holds the .FOR loop counter.  The effec-
tive address must use a memory alterable 
addressing mode (e.g.  it cannot be an immediate 
value).

<op2>	The initial value of the .FOR loop counter.  The 
effective address may be any mode, and may rep-
resent an arbitrary assembler expression (Chap-
ter 3).

<op3>	The terminating value of the .FOR loop counter.  
The effective address may be any mode, and may 
represent an arbitrary assembler expression 
(Chapter 3).

<op4>	The step (increment/decrement) of the .FOR loop 
counter each time through the loop.  If not spec-
ified, it defaults to a value of #1.  The effec-
tive address may be any mode, and may represent 
an arbitrary assembler expression (Chapter 3).

<cnt>	The terminating value in a .LOOP statement.  This 
can be any arbitrary assembler expression (Chap-
ter 3).

All structured control statements may be followed by normal assem-
bler comments on the same logical line.

7.3.1	  .BREAK Statement

SYNTAX:

	.BREAK

FUNCTION:

The .BREAK statement causes an immediate exit from the 
innermost enclosing loop construct (.WHILE, .REPEAT, 
.FOR, .LOOP).

NOTES:

A .BREAK statement does not exit an .IF-THEN-.ELSE con-
struct.  If a .BREAK is encountered with no loop state-
ment active, a warning is issued.

.BREAK should be used with care near .ENDL directives or 
near the end of DO loops.  It generates a jump instruc-
tion which is illegal in those contexts.

EXAMPLE:

	.WHILE  	x:(r1)+ <GT> #0	;loop until zero is found
	.
	.
	.
	.IF	<cs>
	.BREAK		;causes exit from WHILE 
loop
	.ENDI
	.
	.		;any instructions here 
are skipped
	.
	.ENDW
	;execution resumes here after .BREAK

7.3.2	  .CONTINUE Statement

SYNTAX:

	.CONTINUE

FUNCTION:

The .CONTINUE statement causes the next iteration of a 
looping construct (.WHILE, .REPEAT, .FOR, .LOOP) to be-
gin.  This means that the loop expression or operand com-
parison is performed immediately, bypassing any 
subsequent instructions.

NOTES:

If a .CONTINUE is encountered with no loop statement ac-
tive, a warning is issued.

.CONTINUE should be used with care near .ENDL directives 
or near the end of DO loops.  It generates a jump in-
struction which is illegal in those contexts.

One or more .CONTINUE directives inside a  .LOOP con-
struct will generate a NOP instruction just before the 
loop address.

EXAMPLE:

	.REPEAT
	.
	.
	.
	.IF	<cs>
	.CONTINUE		;causes immediate jump to 
.UNTIL
	.ENDI
	.
	.		;any instructions here are 
skipped
	.
	.UNTIL	x:(r1)+ <EQ> #0	;evaluation here after .CON-
TINUE

7.3.3	  .FOR Statement

SYNTAX:

	.FOR <op1> = <op2>  {TO | DOWNTO} <op3> [BY <op4>] [DO]

	<stmtlist>

	.ENDF

FUNCTION:

Initialize <op1> to <op2> and perform <stmtlist> until 
<op1> is greater (TO) or less than (DOWNTO) <op3>.  Makes 
use of a user-defined operand, <op1>, to serve as a loop 
counter.  .FOR-TO allows counting upward, while .FOR-
DOWNTO allows counting downward.  The programmer may 
specify an increment/decrement step size in <op4>, or 
elect the default step size of #1 by omitting the BY 
clause.  A .FOR-TO loop is not executed if <op2> is 
greater than <op3> upon entry to the loop.  Similarly, a 
.FOR-DOWNTO loop is not executed if <op2> is less than 
<op3>.

NOTES:

<op1> must be a writable register or memory location.  It 
is initialized at the beginning of the loop, and updated 
at each pass through the loop.  Any immediate operands 
must be preceded by a pound sign (#).  Memory references 
must be preceded by a memory space qualifier (X:, Y:, or 
P:).  L memory references are not allowed.  Operands must 
be or refer to single-word values.

The logic generated by the .FOR directive makes use of 
several DSP data registers (see Appendix F).  In fact, 
two data registers are used to hold the step and target 
values, respectively, throughout the loop; they are nev-
er reloaded by the generated code.  It is recommended 
that these registers not be used within the body of the 
loop, or that they be saved and restored prior to loop 
evaluation.

The DO keyword is optional.

EXAMPLE:

	.FOR	X:CNT  =  #0  TO  Y:(targ*2)+114	; loop on X:CNT
	.
	.
	.
	.ENDF

7.3.4	  .IF Statement

SYNTAX:

	.IF	<expression>	[THEN]
	<stmtlist>
	[.ELSE
	<stmtlist>]
	.ENDI

FUNCTION:

If <expression> is true, execute <stmtlist> following 
THEN (the keyword THEN is optional); if <expression> is 
false, execute <stmtlist> following .ELSE, if present; 
otherwise, advance to the instruction following .ENDI.

NOTES:

In the case of nested .IF-THEN-.ELSE statements, each 
.ELSE refers to the most recent .IF-THEN sequence.

EXAMPLE:

	.IF	<EQ>	; zero bit set?
	.
	.
	.
	.ENDI

7.3.5	  .LOOP Statement

SYNAX:

	.LOOP  <cnt>
	<stmtlist>
	.ENDL

FUNCTION:

Execute <stmtlist> <cnt> times.  This is similar to the 
.FOR loop construct, except that the initial counter and 
step value are implied to be #1.  It is actually a short-
hand method for setting up a hardware DO loop on the DSP, 
without having to worry about addressing modes or label 
placement.

NOTES:

Since the .LOOP statement generates instructions for a 
hardware DO loop, the same restrictions apply as to the 
use of certain instructions near the end of the loop, 
nesting restrictions, etc.

One or more .CONTINUE directives inside a  .LOOP con-
struct will generate a NOP instruction just before the 
loop address.

EXAMPLE:

	.LOOP	LPCNT	; hardware loop LPCNT times
	.
	.
	.
	.ENDL

7.3.6	  .REPEAT Statement

SYNTAX:

	.REPEAT
	<stmtlist>
	.UNTIL  <expression>

FUNCTION:

<stmtlist> is executed repeatedly until <expression> is 
true.  When expression becomes true, advance to the next 
instruction following .UNTIL.

NOTES:

The <stmtlist> is executed at least once, even if <ex-
pression> is true upon entry to the .REPEAT loop.

EXAMPLE:

	.REPEAT
	.
	.
	.
	.UNTIL	x:(r1)+ <EQ> #0	; loop until zero is found

7.3.7	  .WHILE Statement

SYNTAX:

	.WHILE	<expression>	[DO]

	<stmtlist>

	.ENDW

FUNCTION:

The <expression> is tested before execution of <st-
mtlist>.  While <expression> remains true, <stmtlist> is 
executed repeatedly.  When <expression> evaluates false, 
advance to the instruction following the .ENDW state-
ment.

NOTES:

If <expression> is false upon entry to the .WHILE loop, 
<stmtlist> is not executed; execution continues after 
the .ENDW directive.

The DO keyword is optional.

EXAMPLE:

	.WHILE	x:(r1)+ <GT> #0	; loop until zero is found
	.
	.
	.
	.ENDW

7.4	  SIMPLE AND COMPOUND EXPRESSIONS

Expressions are an integral part of .IF, .REPEAT, and .WHILE state-
ments. Structured control statement expressions should not be con-
fused with the assembler expressions discussed in Chapter 3. The 
latter are evaluated at assembly time and will be referred to here 
as "assembler expressions"; they can serve as operands in struc-
tured control statement expressions. The structured control state-
ment expressions described below are evaluated at run time and will 
be referred to in the following discussion simply as "expressions".

A structured control statement expression may be simple or com-
pound.  A compound expression consists of two or more simple ex-
pressions joined by either AND or OR (but not both in a single 
compound expression).

7.4.1	  Simple Expressions

Simple expressions are concerned with the bits of the Condition 
Code Register (CCR).  These expressions are of two types.  The first 
type merely tests conditions currently specified by the contents 
of the CCR (section 7.4.1.1).  The second type sets up a comparison 
of two operands to set the condition codes, and afterwards tests 
the codes (section 7.4.1.2).

7.4.1.1	  Condition Code Expressions

A variety of tests (identical to those in the Jcc instruction) may 
be performed, based on the CCR condition codes.  The condition 
codes, in this case, are preset by either a user-generated instruc-
tion or a structured operand-comparison expression (section 
7.4.1.2).  Each test is expressed in the structured control state-
ment by a mnemonic enclosed in angle brackets; the mnemonics are 
described in Appendix F, Condition Code Mnemonics.

When processed by the assembler, the expression generates an in-
verse conditional jump to beyond the matching .ENDx/.UNTIL direc-
tive. For example:

	.IF	<EQ>	;zero bit set?
+	bne	Z_L00002	;code generated by assembler
	CLR	D1	;user code
	.ENDI
+	Z_L00002		;assembler-generated label
	.REPEAT		;subtract until D0 < D7
+	Z_L00034		;assembler-generated label
	SUB	D7,D0	;user code
	.UNTIL	<LT>
+	bge	Z_L00034	;code generated by assembler

7.4.1.2	  Operand Comparison Expressions

Two operands may be compared in a simple expression, with subse-
quent transfer of control based on that comparison.  Such a com-
parison takes the form:

	<op1>  <cc>  <op2>

where <cc> is a condition mnemonic enclosed in angle brackets (as 
described in section 7.4.1.1), and <op1> and <op2> are register or 
memory references, symbols, or assembler expressions.  When pro-
cessed by the assembler, the operands are arranged such that a com-
pare/jump sequence of the following form always results:

	CMP	<reg1>,<reg2>
	(J|B)cc	<label>

where the jump conditional is the inverse of <cc>.  Ordinarily 
<op1> is moved to the <reg1> data register and <op2> is moved to 
the <reg2> data register prior to the compare.  This is not always 
the case, however: if <op1> happens to be <reg2> and <op2> is 
<reg1>, an intermediate register is used as a scratch register.  In 
any event, worst case code generation for a given operand compar-
ison expression is generally two moves, a compare, and a condition-
al jump.

Jumps or branches generated by structured control statements are 
forced long because the number and address of intervening instruc-
tions between a control statement and its termination are not known 
by the assembler. The programmer may circumvent this behavior by 
use of the SCSJMP directive (see Chapter 6).

Any immediate operands must be preceded by a pound sign (#).  Memory 
references must be preceded by a memory space qualifier (X:, Y:, 
or P:).  L memory references are not allowed.  Operands must be or 
refer to single-word values.

Note that values in the <reg1> and <reg2> data registers are not 
saved before expression evaluation.  This means that any user data 
in those registers will be overwritten each time the expression is 
evaluated at runtime.  The programmer should take care either to 
save needed contents of the registers, reassign data registers us-
ing the SCSREG directive, or not use them at all in the body of the 
particular structured construct being executed.  The data registers 
used by the structured control statements are listed in Appendix F.

7.4.2	  Compound Expressions

A compound expression consists of two or more simple expressions 
(section 7.4.1) joined by a logical operator (AND or OR).  The bool-
ean value of the compound expression is determined by the boolean 
values of the simple expressions and the nature of the logical op-
erator.  Note that the result of mixing logical operators in a com-
pound expression is undefined:

	.IF	X1  <GT>  B  AND  <LS>  AND  R1  <NE>  R2	;this is 
OK
	.IF	X1  <LE>  B  AND  <LC>  OR   R5  <GT>  R6	;unde-
fined

The simple expressions are evaluated left to right.  Note that this 
means the result of one simple expression could have an impact on 
the result of subsequent simple expressions, because of the condi-
tion code settings stemming from the assembler-generated compare.

If the compound expression is an AND expression and one of the sim-
ple expressions is found to be false, any further simple expres-
sions are not evaluated.  Likewise, if the compound expression is 
an OR expression and one of the simple expressions is found to be 
true, any further simple expressions are not evaluated.  In these 
cases, the compound expression is either false or true, respective-
ly, and the condition codes reflect the result of the last simple 
expression evaluated.

7.5	  STATEMENT FORMATTING

The format of structured control statements differs somewhat from 
normal assembler usage.  Whereas a standard assembler line is split 
into fields separated by blanks or tabs, with no white space inside 
the fields, structured control statement formats vary depending on 
the statement being analyzed.  In general, all structured control 
directives are placed in the opcode field (with an optional label 
in the label field) and white space separates all distinct fields 
in the statement.  Any structured control statement may be followed 
by a comment on the same logical line.

7.5.1	  Expression Formatting

Given an expression of the form:

	<op1>  <LT>  <op2>  OR  <op3>  <GE>  <op4>

there must be white space (blank, tab) between all operands and 
their associated operators, including boolean operators in com-
pound expressions.  Moreover, there must be white space between the 
structured control directive and the expression, and between the 
expression and any optional directive modifier (THEN, DO).  An as-
sembler expression (Chapter 3) used as an operand in a structured 
control statement expression must not have white space in it, since 
it is parsed by the standard assembler evaluation routines:

	.IF	#@CVI(@SQT(4.0))  <GT>  #2	; no white space in first 
operand

7.5.2	  .FOR/.LOOP Formatting

The .FOR and .LOOP directives represent special cases.  The .FOR 
structured control statement consists of several fields:

	.FOR  <op1>  =  <op2>  TO  <op3>  BY  <op4>  DO

There must be white space between all operands and other syntactic 
entities such as =, TO, BY, and DO.  As with expression formatting, 
an assembler expression used as an operand must not have white 
space in it:

	.FOR  X:CNT  =  #0  TO  Y:(targ*2)+1  BY  
#@CVI(@POW(2.0,@CVF(R)))

In the example above, the .FOR loop operands represented as assem-
bler expressions (symbol, function) do not have embedded white 
space, whereas the loop operands are always separated from struc-
tured control statement keywords by white space.

The count field of a .LOOP statement must be separated from the 
.LOOP directive by white space.  The count itself may be any arbi-
trary assembler expression, and therefore must not contain embedded 
blanks.

7.5.3	  Assembly Listing Format

Structured control statements begin with the directive in the op-
code field; any optional label is output in the label field.  The 
rest of the statement is left as is in the operand field, except 
for any trailing comment; the X and Y data movement fields are ig-
nored.  Comments following the statement are output in the comment 
field (unless the unreported comment delimiter is used; see Chapter 
6).

Statements are expanded using the macro facilities of the assem-
bler.  Thus the generated code can be sent to the listing by spec-
ifying the MEX assembler option, either via the OPT directive 
(Chapter 6) or the -O command line option (Chapter 1).

7.6	  EFFECTS ON THE PROGRAMMER'S ENVIRONMENT

During assembly, global labels beginning with "Z_L" are generated. 
They are stored in the symbol table and should not be duplicated 
in user-defined labels. Because these non-local labels ordinarily 
are not visible to the programmer there can be problems when local 
(underscore) labels are interspersed among structured control 
statements. The SCL option (see the OPT directive, Chapter 6) caus-
es the assembler to maintain the current local label scope when a 
structured control statement label is encountered.

In the .FOR loop, <op1> is a user-defined symbol.  When exiting the 
loop, the memory/register assigned to this symbol contains the val-
ue which caused the exit from the loop.

A compare instruction is produced by the assembler whenever two 
operands are tested in a structured statement.  At runtime, these 
assembler-generated instructions set the condition codes of the CCR 
(in the case of a loop, the condition codes are set repeatedly).  
Any user-written code either within or following a structured 
statement that references CCR directly (move) or indirectly (con-
ditional jump/transfer) should be attentive to the effect of these 
instructions.

Jumps or branches generated by structured control statements are 
forced long because the number and address of intervening instruc-
tions between a control statement and its termination are not known 
by the assembler. The programmer may circumvent this behavior by 
use of the SCSJMP directive (see Chapter 6).

In all structured control statements except those using only a sin-
gle condition code expression, registers are used to set up the 
required counters and comparands. In some cases, these registers 
are effectively reserved; the .FOR loop uses two data registers to 
hold the step and target values, respectively, and performs no 
save/restore operations on these registers. The assembler, in fact, 
does no save/restore processing in any structured control opera-
tion; it simply moves the operands into appropriate registers to 
execute the compare. See Appendix F for a list of registers used 
by the assembler in support of structured control statements on a 
particular processor. The SCSREG directive (Chapter 6) may be used 
to reassign structured control statement registers. The MEX assem-
bler option (see the OPT directive, Chapter 6) may be used to send 
the assembler-generated code to the listing file for examination 
of possible register use conflicts.


Appendix A

ASCII CHARACTER CODES

	Decimal	Hex	ASCII	Decimal	Hex	ASCII

	0	00	NUL	64	40	@
	1	01	SOH 	65	41	A
	2	02	STX	66	42	B
	3	03	ETX	67	43	C
	4	04	EOT	68	44	D
	5	05	ENQ	69	45	E
	6	06	ACK	70	46	F
	7	07	BEL	71	47	G
	8	08	BS	72	48	H
	9	09	HT	73	49	I
	10	0A	LF	74	4A	J
	11	0B	VT	75	4B	K
	12	0C	FF	76	4C	L
	13	0D	CR	77	4D	M
	14	0E	S0	78	4E	N
	15	0F	S1	79	4F	O
	16	10	DLW	80	50	P
	17	11	DC1	81	51	Q
	18	12	DC2	82	52	R
	19	13	DC3	83	53	S
	20	14	DC4	84	54	T
	21	15	NAK	85	55	U
	22	16	SYN	86	56	V
	23	17	ETB	87	57	W
	24	18	CAN	88	58	X
	25	19	EM 	89	59	Y
	26	1A	SUB	90	5A	Z
	27	1B	ESC	91	5B	[
	28	1C	FS	92	5C	\
	29	1D	GS	93	5D	]
	30	1E	RS	94	5E	^
	31	1F	US	95	5F	_
	32	20	SP	96	60	`
	33	21	!	97	61	a
	34	22	" 	98	62	b
	35	23	#	99	63	c
	Decimal	Hex	ASCII	Decimal	Hex	ASCII

	36	24	$	100	64	d
	37	25	%	101	65	e
	38	26	& 	102	66	f
	39	27	'	103	67	g
	40	28	(	104	68	h
	41	29	)	105	69	i
	42	2A	*	106	6A	j
	43	2B	+	107	6B	k
	44	2C	,	108	6C	l
	45	2D	-	109	6D	m
	46	2E	.	110	6E	n
	47	2F	/	111	6F	o
	48	30	0	112	70	p
	49	31	1	113	71	q
	50	32	2	114	72	r
	51	33	3	115	73	s
	52	34	4	116	74	t
	53	35	5	117	75	u
	54	36	6	118	76	v
	55	37	7	119	77	w
	56	38	8	120	78	x
	57	39	9	121	79	y
	58	3A	:	122	7A	z
	59	3B	;	123	7B	{
	60	3C	<	124	7C	|
	61	3D	=	125	7D	}
	62	3E	>	126	7E	~
	63	3F	?	127	7F	DEL


Appendix B

DIRECTIVE SUMMARY

Assembler directives can be grouped by function into seven types:

1.  Assembly control
2.  Symbol definition
3.  Data definition/storage allocation
4.  Listing control and options
5.  Object file control
6.  Macros and conditional assembly
7.  Structured programming

B.1	  ASSEMBLY CONTROL

The directives used for assembly control are:

COMMENT	- Start comment lines
DEFINE	- Define substitution string
END 	- End of source program
FAIL	- Programmer generated error message
FORCE	- Set operand forcing mode
HIMEM	- Set high memory bounds
INCLUDE	- Include secondary file
LOMEM	- Set low memory bounds
MODE	- Change relocation mode
MSG	- Programmer generated message
ORG	- Initialize memory space and location 
counters
RADIX	- Change input radix for constants
RDIRECT	- Remove directive or mnemonic from table
SCSJMP	- Set structured control branching mode
SCSREG	- Reassign structured control statement regis-
ters
UNDEF	- Undefine DEFINE symbol
WARN	- Programmer generated warning

B.2	  SYMBOL DEFINITION

The directives used to control symbol definition are:

ENDSEC	- End section
EQU	- Equate symbol to a value
GLOBAL	- Global section symbol declaration
GSET	- Set global symbol to a value
LOCAL	- Local section symbol declaration
SECTION	- Start section
SET	- Set symbol to a value
XDEF	- External section symbol definition
XREF	- External section symbol reference

B.3	  DATA DEFINITION/STORAGE ALLOCATION

The directives used to control constant data definition and storage 
allocation are:

BADDR	- Set buffer address
BSB	- Block storage bit-reverse
BSC	- Block storage of constant
BSM	- Block storage modulo
BUFFER	- Start buffer
DC	- Define constant
DCB	- Define constant byte
DS	- Define storage
DSM	- Define modulo storage
DSR	- Define reverse carry storage
ENDBUF	- End buffer

B.4	  LISTING CONTROL AND OPTIONS

The directives used to control the output listing are:

LIST	- List the assembly
LSTCOL	- Set listing field widths
NOLIST	- Stop assembly listing
OPT	- Assembler options
PAGE	- Top of page/size page
PRCTL	- Send control string to printer
STITLE	- Initialize program subtitle
TABS	- Set listing tab stops
TITLE	- Initialize program title

B.5	  OBJECT FILE CONTROL

The directives used for control of the object file are:

COBJ	- Comment object code
IDENT	- Object code identification record
SYMOBJ	- Write symbol information to object file

B.6	  MACROS AND CONDITIONAL ASSEMBLY

The directives used for macros and conditional assembly are:

DUP	- Duplicate sequence of source lines
DUPA	- Duplicate sequence with arguments
DUPC	- Duplicate sequence with characters
DUPF	- Duplicate sequence in loop
ENDIF	- End of conditional assembly
ENDM	- End of macro definition
EXITM	- Exit macro
IF	- Conditional assembly directive
MACLIB	- Macro library
MACRO	- Macro definition
PMACRO	- Purge macro definition

B.7	  STRUCTURED PROGRAMMING

The directives used for structured programming are:

.BREAK	- Exit from structured loop construct
.CONTINUE	- Continue next iteration of structured loop
.ELSE	- Perform following statements when .IF false
.ENDF	- End of .FOR loop
.ENDI	- End of .IF condition
.ENDL	- End of hardware loop
.ENDW	- End of .WHILE loop
.FOR	- Begin .FOR loop
.IF	- Begin .IF condition
.LOOP	- Begin hardware loop
.REPEAT	- Begin .REPEAT loop
.UNTIL	- End of .REPEAT loop
.WHILE	- Begin .WHILE loop


Appendix C

ASSEMBLER MESSAGES

C.1	  INTRODUCTION

Assembler messages are grouped into four categories:

Command Line Errors

These errors indicate invalid command line options, missing 
filenames, file open errors, or other invocation errors.  Com-
mand line errors generally cause the assembler to stop pro-
cessing.

Warnings

Warnings notify the programmer of suspect constructs but do 
not otherwise affect the object file output.

Errors

These errors indicate problems with syntax, addressing modes, 
or usage.  In these cases the resulting object code is gener-
ally not valid.

Fatal

Fatal errors signify serious problems encountered during the 
assembly process such as lack of memory, file not found, or 
other internal errors.  The assembler halts immediately.

The assembler also will provide information on the source field 
location of the error, if it can be ascertained.  If a listing file 
is produced, messages ordinarily will appear immediately before the 
line containing the error.  One exception is when the relationship 
between the first and last instructions in a DO loop produces an 
error.  In this case the error text will appear after the last in-
struction at the end of the loop.  Messages are always routed to 
standard output.

C.2	  COMMAND LINE ERRORS

Cannot open command file
Cannot open listing file
Cannot open object file

The file associated with a -F, -L, or -B command line option 
was not found.

Cannot open source file

The assembly source input file was not found.

Duplicate listing file specified - ignored
Duplicate object file specified - ignored

The -L and -B command line options were encountered more than 
once on the command line.  Only the first occurrence of each 
option is used.  The assembler continues processing.

Illegal command line -D option argument

The symbol name given in a -D command line option is invalid 
(possibly too long or does not begin with an alphabetic char-
acter), or the substitution string is not enclosed in single 
quotes.

Illegal command line -I option argument

A problem occurred when attempting to save the include file 
path string.

Illegal command line -M option argument

A problem occurred when attempting to save the MACLIB file 
path string.

Illegal command line -P option argument

The string provided as the processor type is not valid.

Illegal command line -R option argument

The string provided as the revision level is not valid.

Illegal command line option

The option specified on the command line was not recognized 
by the assembler.

Interrupted

The assembler was interrupted by a keyboard break (Control-C).

LDB option with no listing file specified; using source file

The LDB option was given on the command line without a corre-
sponding -L to generate a listing file. If a listing file is 
not produced, debugging packages cannot use it for source 
tracking. Therefore the assembler uses the default assembly 
language file as input for source tracking.

Missing command line option argument

The expected arguments following a command line option spec-
ifier were missing.

Missing source filename

There must be at least one source filename specified on the 
command line.

Source file name same as listing file name
Source file name same as object file name

One of the source files appeared to the assembler to have the 
same name as the specified listing or object file.  The as-
sembler aborts rather than potentially writing over a source 
input file.

C.3	  WARNINGS

Absolute address involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, an operand was eval-
uated with a different memory space attribute than that spec-
ified in the instruction.

Absolute address too large to use I/O short - long substituted

The absolute address is not within the range specifying an I/
O short address, even though the I/O short forcing operator 
has been used. The assembler substitutes long absolute ad-
dressing.

Absolute address too large to use short - long substituted

The absolute address value being forced short will not fit in 
the storage allocated for a short address. The assembler sub-
stitutes long absolute addressing.

Absolute address too small to use I/O short - long substituted

The absolute address is not within the range specifying an I/
O short address, even though the I/O short forcing operator 
has been used. The assembler substitutes long absolute ad-
dressing.

Address involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, an operand was eval-
uated with a different memory space attribute than that spec-
ified in the instruction.

Cannot force short addressing for source and destination

In a MOVEP or MOVES instruction an attempt was made to force 
both operands to short or I/O short.  The second operand de-
faults to long.

Cannot force short immediate with this parallel move

The immediate operand in the X field of a parallel X memory 
and register move cannot be forced short.  The mode is changed 
to long immediate.

Contents of assigned register in previous instruction not available 
-
	generating NOP instruction

Due to pipelining, if an address register (Rn or Nn) is 
changed in the previous instruction, the new contents are not 
available for use as a pointer until the next instruction. If 
the RP option is in effect (see the OPT directive, Chapter 6) 
the assembler produces this warning and generates a NOP prior 
to the offending instruction.

Debug directives ignored - use command line debug option

A source-level debug directive was encountered but the assem-
bler command line -G option was not given.

Destination operand assumed I/O short

Neither operand in a MOVEP instruction is explicitly declared 
I/O short; however, the source operand does not qualify, so 
the destination operand is assumed to be the I/O short oper-
and.

Directive not allowed in command line absolute mode

The MODE directive is ignored when the assembler command line 
-A option is active.

Duplicate listing file specified - ignored
Duplicate object file specified - ignored

The -B or -L command line options were given more than once.

ENDDO instruction not inside DO loop

An ENDDO instruction was found outside the scope of an active 
DO loop.

Explicit bottom margin ignored with page length of zero
Explicit top margin ignored with page length of zero

The top or bottom margin parameters to a PAGE directive are 
ignored because the page length parameter was zero.

Expression involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, two operands were 
evaluated with different memory space attributes, neither of 
which was N.

Expression value outside fractional domain

The expected fractional value was not within the range  -1.0 
<= m < 1.

Extra dimensions ignored

A source-level debug .DIM directive contained more than four 
arguments specifying the dimensions of an array.

FMPY suffix ignored - using secondary opcode suffix

The single or extended precision suffix on a dual-opcode in-
struction has been ignored.  The precision is taken from the 
suffix on the secondary opcode.

Immediate value too large to use short - long substituted

An immediate data value being forced short is too large to fit 
in the space allocated for a short immediate value.  The as-
sembler substitutes long immediate addressing.

Improper nesting of DO loops

The end address of a subordinate (nested) DO loop is greater 
than or equal to the end address of the loop enclosing it.  
The end address of a nested DO instruction must be less than 
the end address of the enclosing loop.

Instruction cannot appear in interrupt vector locations

Some instructions cannot be used reliably as interrupt code. 
These instructions include RTI, RTS, DO, and ENDDO.

Instruction does not allow data movement specified - using MOVE 
encoding
Instruction does not allow data movement specified - using MOVEP 
encoding
Instruction does not allow data movement specified - using MOVES 
encoding

An inappropriate MOVE-type instruction was written given the 
type of the operands.  The assembler substitutes a valid en-
coding for the operands in question.

Invalid destination register for this instruction - using TFR3 en-
coding

The destination register for a TFR2 instruction was not either 
X or Y.

Invalid interrupt vector address - using SWI address

Currently only the SWI address is supported by the TRAPcc in-
struction.

I/O short absolute address cannot be forced

I/O short absolute addressing is not valid for this operation.  
An appropriate addressing mode (long absolute, short jump, 
short absolute) is substituted.

I/O short absolute address cannot be forced - long substituted

I/O short absolute addressing is not valid for this operation.  
The assembler substitutes long absolute addressing.

I/O short address cannot be forced

I/O short addressing is not valid for this operation.  An ap-
propriate addressing mode (long, short, short jump) is sub-
stituted.

I/O short address cannot be forced - long substituted

I/O short addressing is not valid for this operation.  The 
assembler substitutes long addressing.

Label field ignored

The assembler directive does not allow a label, so the assem-
bler will not store the label value in the symbol table.

Load location counter overflow
Load location counter underflow

The load location counter exceeded its maximum or minimum val-
ue.  The assembler wraps the counter value around and contin-
ues.

Load origin involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, an operand was eval-
uated with a different memory space attribute than that spec-
ified in the directive.

Load reserved address space violation

The load location counter has incremented into a reserved area 
of data address space.

Long absolute address cannot be forced

Long absolute addressing is not valid for this operation.  An 
appropriate addressing mode (I/O absolute, short jump, short 
absolute) is substituted.

Long absolute address cannot be forced - substituting I/O short 
addressing

Long absolute addressing is not valid for this operation.  The 
assembler substitutes I/O short addressing.

Long absolute address cannot be forced - substituting short ad-
dressing

Long absolute addressing is not valid for this operation.  The 
assembler substitutes short absolute addressing.

Long immediate cannot be forced

Long immediate data is not valid for this operation.  An ap-
propriate size for the target DSP is substituted.

Long PC-relative address cannot be forced

Long PC-relative addressing is not valid for this operation.  
An appropriate addressing mode (short PC-relative) is substi-
tuted.

Macro expansion not active

A macro must have been called prior to using the @ARG() or 
@CNT() functions (see Chapter 3).

Macro name is the same as existing assembler directive
Macro name is the same as existing assembler mnemonic

The name of the macro being defined conflicts with the name 
of an assembler directive or mnemonic.  Either use a different 
macro name or use the RDIRECT directive to remove the direc-
tive or mnemonic name from the assembler lookup tables.

No control registers accessed - using MOVE encoding

A MOVEC-type instruction was given but no control registers 
were used as operands. The assembler substitutes a valid en-
coding for the operands in question.

No looping construct found - .BREAK ignored
No looping construct found - .CONTINUE ignored

A .BREAK or .CONTINUE structure control statement was encoun-
tered outside of any active looping construct (.FOR, .LOOP, 
.REPEAT, .WHILE).

Number of macro expansion arguments is greater than definition
Number of macro expansion arguments is less than definition

A discrepancy exists between the number of arguments specified 
in a macro definition and the number of arguments provided in 
the macro call.

Options for both debug and strip specified - strip ignored

Both the -G and -Z options were given on the command line. The 
-G option takes precedence.

P space not accessed - using MOVE encoding

A MOVEP-type instruction was given but a P memory reference 
was not used as an operand. The assembler substitutes a valid 
encoding for the operands in question.

Page directive with no arguments ignored with page length of zero

A PAGE directive with no arguments, which ordinarily produces 
a form feed in the listing output, is ignored because a pre-
vious PAGE directive specified a page length of zero.

PC-relative address involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, an operand was eval-
uated with a different memory space attribute than that spec-
ified in the instruction.

PC-relative address too large to use short - long substituted

The PC-relative offset is not within the range specifying a 
short PC-relative offset, even though the short forcing oper-
ator has been used. The assembler substitutes long PC-relative 
addressing.

Post-update operation will not occur on destination register

If the source operand in a MOVE operation specifies a post-
update addressing mode and the destination register is the 
same as the source operand register then the post-update op-
eration will not take place.

PRCTL directive ignored - no explicit listing file

The PRCTL directive takes effect only if the -L option is used 
on the command line to explicitly specify a listing file.

Redefinition of symbol

A symbol used in a DEFINE directive has been redefined without 
an intervening UNDEF directive. The assembler discards the 
previous definition and replaces it with the new definition.

Rounding not available with LMS move - using MAC/MPY encoding

A MACR or MPYR instruction was specified in conjunction with 
LMS move syntax.

Runtime location counter overflow
Runtime location counter underflow

The runtime location counter exceeded its maximum or minimum 
value.  The assembler wraps the counter value around and con-
tinues.

Runtime origin involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, an operand was eval-
uated with a different memory space attribute than that spec-
ified in the directive.

Runtime reserved address space violation

The runtime location counter has incremented into a reserved 
area of data address space.

Short absolute address cannot be forced

Short absolute addressing is not valid for this operation. An 
appropriate addressing mode (long absolute) is substituted.

Short absolute address cannot be forced - long substituted

Short absolute addressing is not valid for this operation. The 
assembler substitutes long absolute addressing.

Short immediate cannot be forced

Short immediate data is not valid for this operation.  An ap-
propriate size is substituted.

Short PC-relative address cannot be forced

Short PC-relative addressing is not valid for this operation. 
An appropriate addressing mode (long PC-relative) is substi-
tuted.

Signed operand must come first in signed/unsigned combinations

In a MPYSU, MACSU, or DMACSU instruction, the signed operand 
must come first in the operand ordering.

Source operand assumed I/O short

Neither operand in a MOVEP instruction is explicitly declared 
I/O short; however, the destination operand does not qualify, 
so the source operand is assumed to be the I/O short operand.

Storage block size not a power of 2

The expression in a DSR directive did not evaluate to a power 
of 2. Since the DSR directive is generally used to allocate 
FFT buffers for reverse carry operations, the size of the 
buffer may be in error.

String truncated in expression evaluation

Only the first four characters of a string constant are used 
during expression evaluation except for arguments to the DC 
directive (see Chapter 6).

Strip not valid in relocatable mode - ignored

The -Z option is valid only when the -A option is also given.

Unresolved external reference

Ordinarily the assembler does not flag unresolved references 
in relative mode, assuming they will be resolved at link time. 
If the UR option is specified, the assembler will generate 
this warning if any symbols are undefined during the second 
pass.

C.4	  ERRORS

Absolute address contains forward reference - force short or I/O 
short address

The assembler attempted a default to short addressing which 
failed.  Either the absolute address is too large or it needs 
to be forced I/O short.

Absolute address must be either short or I/O short

The absolute address is too large for a short address and out-
side the range of valid I/O short addresses.

Absolute address too large to use I/O short
Absolute address too small to use I/O short

The absolute address being forced short is outside the range 
of valid I/O short addresses.  This usually means that the I/
O short address has not been ones extended.

Absolute address too large to use short

The absolute address value is too large to be forced short.

Absolute addressing mode not allowed

Absolute operands are not allowed with some instructions, in 
particular parallel XY data memory moves.

Address mode syntax error - expected ')'
Address mode syntax error - expected '+'
Address mode syntax error - expected '+' or '-'
Address mode syntax error - expected comma
Address mode syntax error - expected comma or end of field
Address mode syntax error - expected offset register
Address mode syntax error - extra characters
Address mode syntax error - probably missing ')'

A syntax error was detected when scanning the source line op-
erand and/or X and Y data fields.  These errors may indicate 
omission of a source operand, insufficient white space between 
fields, or improper specification of address register indi-
rect addressing modes.

Argument outside function domain

An argument to one of the transcendental built-in functions 
was inappropriate.

Arithmetic exception

An internal floating point exception occurred while evaluat-
ing an expression.  The result of the evaluation is probably 
not valid.

Assembler directive or mnemonic not found

An argument to the RDIRECT directive was not a recognized as-
sembler directive or mnemonic.

Base argument larger than machine word size

The base parameter of a @FLD() function has a value larger 
than can fit in the target machine word.

Binary constant expected

A character other than ASCII '0' or '1' either followed the 
binary constant delimiter (%) or appeared in an expression 
where a binary value was expected by default.

Bit mask cannot span more than eight bits

If the first operand of a BFxxx-type instruction was shifted 
one bit to the right until the low-order bit was a 1, the re-
sulting value must not exceed $FF hexadecimal.

Cannot conditionally repeat write to memory

A move to memory cannot be preceded by a REPcc-type instruc-
tion.

Cannot nest section inside itself

A section of a given name may not have another SECTION direc-
tive with the same name declared inside it.

Cannot nest symbol definitions

A source-level debug .DEF directive was encountered inside an-
other .DEF-.ENDEF pair.

Cannot open include file

The specified INCLUDE file cannot be found, or the operating 
system limit on open files has been exceeded.

Cannot repeat this instruction
Cannot repeat two-word instruction

The REP instruction cannot be used to repeat two-word instruc-
tions or instructions that change program flow. Instructions 
that cannot be repeated include DO, Jcc, JCLR, JMP, JSET, 
JScc, JSCLR, JSR, JSSET, REP, RTI, RTS, and SWI.

CONST option must be used before any label

This option, which prevents EQU symbols from being exported 
to the object file, must be given before any label is encoun-
tered in the source file.

Contents of assigned register in previous instruction not available

Due to pipelining, if an address register (Rn or Nn) is 
changed in the previous instruction, the new contents are not 
available for use as a pointer until the next instruction.

Count must be an integer value

The argument to a DUP directive did not evaluate as an integer 
expression.

CRE option must be used before any label

The CRE option must be activated before any labels are encoun-
tered so that the assembler can append cross-reference data 
to all applicable symbol table entries.

Data allocation exceeds buffer size

Data allocated between a BUFFER-ENDBUF sequence exceeded the 
size specified in the BUFFER directive.

Decimal constant expected

A character other than ASCII '0' through '9' either followed 
the decimal constant delimiter (`) or appeared in an expres-
sion where a decimal value was expected by default.

DEFINE symbol must be a global symbol name

A local label (a symbol beginning with the underscore charac-
ter) may not be used as a DEFINE directive symbol.

Directive not allowed in EMI memory

Any kind of buffer directive is disallowed when the runtime 
memory space is E(MI).

Displacement address mode not allowed

Long displacement addressing is not allowed with some instruc-
tions, in particular parallel XY data memory moves.

Divide by zero

The expression evaluator detected a divide by zero.

DO loop address must be in current section

The loop address of a DO loop cannot fall outside the bounds 
of its enclosing section.  This is particularly important in 
relative mode as the loop address is calculated based on the 
starting address of the section.

Dummy argument not found

The dummy argument name given as an argument to the @ARG() 
function was not found in the macro dummy argument list.

Duplicate destination register not allowed

If the opcode-operand portion of an instruction specifies a 
destination register, the same register or portion of that 
register may not be specified as a destination in the parallel 
data bus move operation.

Duplicate source and destination register not allowed

If the opcode-operand portion of an instruction specifies a 
source register, the same register or portion of that register 
may not be specified as a destination in the parallel data bus 
move operation.

Either source or destination memory space must be X or Y

One of the operands in a MOVEP instruction must reference a 
location in X or Y memory.

ELSE without associated IF directive

An ELSE directive was encountered without a preceding IF con-
ditional assembly directive.

.ELSE without associated .IF directive

An .ELSE directive was encountered before a matching .IF con-
ditional structured control statement.

Empty bit mask field

The first operand of a BFxxx-type instruction was zero.

End of structure or union without matching definition

A source-level debug end-of-structure symbol declaration was 
recognized without a preceding structure or union definition.

ENDBUF without associated BUFFER directive

An ENDBUF directive was encountered without a preceding BUFFER 
directive.

.ENDEF without associated .DEF directive

A source-level debug .ENDEF directive was encountered without 
a preceding .DEF directive.

.ENDF without associated .FOR directive
.ENDI without associated .IF directive

An end-of-conditional or end-of-loop directive was encoun-
tered before a matching conditional or loop structured control 
statement.

ENDIF without associated IF directive

An ENDIF directive was encountered without a preceding IF con-
ditional assembly directive.

.ENDL without associated .LOOP directive

An end-of-loop directive was encountered before a matching 
loop structured control statement.

ENDM without associated MACRO directive

An ENDM directive was encountered without a preceding MACRO 
directive.

ENDSEC without associated SECTION directive

An ENDSEC directive was encountered without a preceding SEC-
TION directive.

.ENDW without associated .WHILE directive

An end-of-loop directive was encountered before a matching 
loop structured control statement.

EQU requires label

The EQU directive must have a label to associate with the 
equated expression.

EXITM without associated MACRO directive

An EXITM directive was encountered without a preceding MACRO 
directive.

Expression cannot have a negative value

Some directives do not allow negative expression arguments, 
as for example in the PAGE directive controls.

Expression contains forward references

Some directives do not allow expression arguments which have 
not yet been defined in the source, as for example in the IF, 
EQU, or SET directives.

Expression involves incompatible memory spaces

The memory space attribute is regarded by the assembler as a 
type, in the same sense that high level languages use type for 
variables. Symbols may have memory space attributes of X, Y, 
L, P(rogram), E(MI), or N(one); only N is fully compatible 
with all other attributes. In this case, two operands were 
evaluated with different memory space attributes, neither of 
which was N.

Expression must be greater than zero

Some directives require a nonzero argument, as for example in 
the BSC directive.

Expression result must be absolute

Certain directives and some assembler usage require absolute 
values as arguments or operands.

Expression result must be integer

Certain directives and some assembler usage require integer 
values as arguments or operands.

Expression result too large

The expression evaluated to a value greater than the accept-
able range. This error can occur when an expression result 
exceeds the native word size of the target DSP.

External reference not allowed in expression

References to external symbols (e.g. symbols not defined in 
the current assembly source input) are not allowed in some 
types of byte or integer expressions.

External reference not allowed in function

References to external symbols (e.g.  symbols not defined in 
the current assembly source input) are not allowed as direct 
or indirect arguments to any built-in function.

Extra characters beyond expression

The expression evaluator found extra characters after the end 
of a valid expression.  Unbalanced parentheses can cause this 
error.

Extra characters following string

An end-of-string delimiter was followed by unexpected charac-
ters on the source line.

Extra characters following symbol name

A non-alphanumeric character other than the underscore (_) was 
encountered in a symbol name.

Extra characters in function argument or missing ')' for function

Mismatched parentheses or wrong number of parameters in a 
function invocation.

Extra characters in operand field

The PAGE directive contains too many operands.

Extra fields ignored

There were extra fields specified in an assembler directive.

First data move destination accumulator same as operand destination 
accumulator

The destination of the data move field is the same as the Data 
ALU destination.

First data move field required with this instruction

A TFR3 instruction requires a register and a data move operand 
field.

First data move source accumulator same as operand destination ac-
cumulator

The source of the data move field is the same as the Data ALU 
destination.

Floating point constant expected

A character other than ASCII '0' through '9', 'e' or 'E', or 
'.' appeared in an expression where a floating point value was 
expected by default.

Floating point not allowed in relative expression

Relative expressions are generally used for address computa-
tion, therefore a floating point value would not be appropri-
ate.

Floating point value not allowed

An immediate value expressed in floating point notation is 
only valid in a MOVE-type instruction.

Forcing not specified

The type of forcing operand was not given in a FORCE direc-
tive.

Function result out of range

The result computed by a transcendental function was too large 
to be represented on the host machine.

GL option must be used before any section

The GL option must be activated before any explicit sections 
are encountered so that the assembler can insure that all sec-
tion symbols are global.

GLOBAL without preceding SECTION directive

A GLOBAL directive was encountered outside any previously de-
fined section.

GS option must be used before any section

The GS option must be activated before any explicit sections 
are encountered so that the assembler can use the appropriate 
counters for section relocation.

Hex constant expected

A character other than ASCII '0' through '9', 'a' through 'f', 
or 'A' through 'F' either followed the hexadecimal constant 
delimiter ($) or appeared in an expression where a hexadecimal 
value was expected by default.

IC option must be used before any symbol, section, or macro defi-
nition

The IC option must be activated before any symbols, sections, 
or macros are defined so that the assembler can remain con-
sistent when storing label names in the symbol table.

IDENT directive must contain revision number
IDENT directive must contain version number

The version and revision numbers are both required arguments 
for the IDENT directive.

Illegal directive in buffer declaration

A directive was encountered between a BUFFER-ENDBUF pair that 
is not allowed in that context. Some invalid directives in-
clude any other buffer-type directive (DSM, DSR, etc.), sec-
tion directives, or any directive which alters the current 
location counter designation (MODE, ORG).

Illegal directive inside .DEF-.ENDEF declaration
Illegal directive outside .DEF-.ENDEF declaration

Some source-level debug directives, such as .FILE, make no 
sense and are not allowed inside .DEF-.ENDEF declarations. 
Conversely, other directives such as .VAL are not allowed out-
side of a .DEF-.ENDEF declaration.

Illegal directive inside DO loop

A directive was encountered inside a DO loop that is not al-
lowed in that context. Some invalid directives include any 
buffer-type directive (DSM, DSR, etc.), section directives, 
or any directive which alters the current location counter 
designation (MODE, ORG).

Illegal function argument

An invalid argument was passed to one of the assembler built-
in functions, in particular the @LCV() function.

Illegal instruction in single-instruction DO loop

A conditional break instruction (BRKcc) cannot be used as the 
only instruction in a DO loop.

Illegal memory counter specified

The memory counter designation supplied in the ORG directive 
was not one of H (high), L (low), or a positive integer ex-
pression in parentheses.

Illegal memory map character

The memory map character supplied in the ORG directive was not 
one of I (internal), E (external), R (ROM), A (port A), or B 
(port B).

Illegal memory space specified
Illegal memory space specified - L:
Illegal memory space specified - P:
Illegal memory space specified - X:
Illegal memory space specified - Y:

The memory space given is either invalid or inappropriate for 
the desired operation.

Illegal move field destination specified
Illegal move field destination register specified

The destination operand in a data memory move is invalid for 
the type of instruction specified.

Illegal move field source specified

The source operand in a data memory move is invalid for the 
type of instruction specified.

Illegal operator for floating point element

Bitwise operators are invalid for floating point values.

Illegal option

An argument to the OPT directive is invalid.

Illegal processor type

The argument to the -P command line option is invalid.

Illegal revision

The argument to the -R command line option is invalid.

Illegal secondary mnemonic

The secondary mnemonic to an FMPY instruction was not one of 
FADD, FSUB, or FADDSUB.

Illegal use of SSH as loop count operand

The contents of the system stack high register may not be used 
as the loop count operand of a DO instruction.

Illegal X field destination specified
Illegal X field destination register specified
Illegal Y field destination specified

The destination operand in an X or Y memory data move is in-
valid for the type of instruction specified.

Illegal Y field source specified

The source operand in an X memory data move is invalid for the 
type of instruction specified.

Immediate addressing mode not allowed

Immediate operands are not allowed with some instructions, in 
particular program memory moves (MOVEM).

Immediate operand not allowed

Immediate operands are not allowed with some instructions, in 
particular program memory moves (MOVEM).

Immediate operand required

The ANDI and ORI instructions must have an immediate value as 
the source operand.

Immediate value too large

The immediate operand value is too large for the space allot-
ted in the instruction.

Immediate value too large to use short

The immediate value being forced short is too large to fit 
into the instruction word.

Increment value cannot be zero

The increment parameter to a DUPF directive must be greater 
than zero.

Indexed address mode not allowed

XY parallel data moves and the LEA instruction do not allow 
indexed addressing mode.

Initial debug directive must be .FILE

In a source file containing debug directives being assembled 
with the -G option the .FILE directive must be the first 
source-level debug directive in the input stream.

Instruction cannot appear at last address of a DO loop
Instruction cannot appear at next to last address of a DO loop
Instruction cannot appear within last 2 words of a DO loop
Instruction cannot appear within last 3 words of a DO loop

Some instructions are restricted within a variable range of 
the DO instruction loop address.  These instructions include 
DO, ENDDO, JMP, Jcc, JCLR, JSET, and moves to or from partic-
ular control registers.

Instruction cannot appear immediately after control register ac-
cess

Some instructions must not appear immediately after certain 
control registers have been accessed.  These instructions in-
clude RTI, RTS, DO, and ENDDO.

Instruction does not allow data movement specified

The desired operation may only be done with a MOVE instruc-
tion.

Invalid address expression

An attempt was made to evaluate an expression consisting of 
two relative terms with the same sign.

Invalid addressing mode

The addressing mode of one of the operands in the instruction 
was not recognized.

Invalid buffer type

The buffer type specified in a BADDR or BUFFER directive was 
not one of M (modulo) or R (reverse-carry).

Invalid conditional register transfer syntax

The syntax for an IFcc or FFcc conditional address register 
move was incorrect.

Invalid destination register

The first data move destination register in a double memory 
read operation was not valid.

Invalid dummy argument name

Macro argument names cannot be local symbols, e.g. they cannot 
begin with the underscore (_) character.

Invalid force type

The argument to a FORCE directive must be SHORT, LONG, or 
NONE.

Invalid function name

The name following the function invocation character (@) was 
not recognized.

Invalid label field width specified

The argument given to the LSTCOL directive does not allow 
enough room on the listing line for the remaining fields to 
be output.

Invalid macro name

Macro names cannot be local symbols, e.g. they cannot begin 
with the underscore (_) character.

Invalid memory space attribute

The memory space attribute given is not one of the letters X, 
Y, L, P, or E.

Invalid mode

The mode specified in a MODE directive was not either RELATIVE 
or ABSOLUTE.

Invalid opcode field width specified
Invalid opcode 2 field width specified
Invalid operand field width specified
Invalid operand 2 field width specified

The argument given to the LSTCOL directive does not allow 
enough room on the listing line for the remaining fields to 
be output.

Invalid page length specified

The minimum page length allowed by the PAGE directive is 10 
lines per page.  The maximum is 255.

Invalid page width specified

The minimum page width allowed by the PAGE directive is 1 col-
umn per line.  The maximum is 255.

Invalid radix expression

The expression in the RADIX directive does not evaluate to one 
of the supported constant bases (2, 8, 10, or 16).

Invalid register combination

The source operand registers in a FMPY instruction cannot be 
used together.

Invalid register specified

The direct register operand is incorrect for this instruction.

Invalid relative expression

The terms of a relative expression may only participate in 
addition and subtraction operations and must have opposing 
signs.

Invalid secondary opcode

The opcode in the second operation field is not one of the 
instructions FADD, FSUB, or FADDSUB.

Invalid section directive modifier

The qualifier specified in a SECTION directive was not either 
GLOBAL or STATIC.

Invalid section name

Section names cannot be local symbols, e.g. they cannot begin 
with the underscore (_) character.

Invalid shift amount

A shift expression must evaluate to within the range 0 <= n 
<= m, where m is the maximum address of the target DSP.

Invalid source address mode

The source address mode in a MOVEP instruction was not valid.

Invalid source address register
Invalid source register

The source register in a double memory read operation was not 
valid.

Invalid storage class

The storage class given in a source-level debug symbol decla-
ration is unknown.

Invalid tabs stops specified

The argument to the TAB directive is out of range.

Invalid X field destination address mode
Invalid X field source address mode

The address mode in the source or destination of the X data 
move field was invalid.

Invalid X field width specified
Invalid Y field width specified

The argument given to the LSTCOL directive does not allow 
enough room on the listing line for the remaining fields to 
be output.

Invalid XY address register specification

In some XY memory parallel data moves, if the register forming 
the effective address of the X data field is from the set R0-
R3, the effective address register in the Y field must be from 
the set R4-R7. Conversely, if the register forming the effec-
tive address of the X data field is from the set R4-R7, the 
effective address register in the Y field must be from the set 
R0-R3.

Invalid XY data register specification

In some XY memory parallel data moves, if the data register 
of the X data field is from the set D0-D3, the data register 
in the Y field must be from the set D4-D7. Conversely, if the 
data register of the X data field is from the set D4-D7, the 
data register in the Y field must be from the set D0-D3.

I/O short addressing mode not allowed

An operand was forced I/O short when I/O short addressing was 
not allowed.

Jump based on SSH or SSL cannot follow update of SP
Jump via SSH or SSL cannot follow write to SP

A JSET, JCLR, JSSET, or JSCLR instruction which tested a bit 
in either the SSH or SSL register was immediately preceded by 
a MOVE to the SP register.

L space specified for load, but not for runtime
L space specified for runtime, but not for load

Since L memory space is the only double-wide memory space, if 
L memory space is the runtime memory space, the only valid 
load memory space is L. Likewise, L memory space can never be 
specified as the load memory space if runtime memory space is 
X, Y, or P.

LB option must be used before any code or data generation

The LB option must be specified before any code or data in 
order for the assembler to increment the location counter ap-
propriately.

LDB option must be used before any code or data generation

The LDB option must be specified before any code or data in 
order for the assembler to establish the debug source file 
appropriately.

Left margin exceeds page width

The blank left margin value in the PAGE directive exceeds the 
default or specified page width parameter.

Length value greater than string size

The length parameter in a substring construct is larger than 
the composite length of the input string argument.

Line too long

Source statements, including continuation lines, cannot ex-
ceed 512 characters in length.

LOC option must be used before any local label

The LOC option must appear before any local label so that the 
assembler can keep the local label lists synchronized.

LOCAL directive not valid in global section

The LOCAL directive is not allowed inside an implicit or ex-
plicit global section.

Local symbol names cannot be used with GLOBAL
Local symbol names cannot be used with LOCAL
Local symbol names cannot be used with XDEF
Local symbol names cannot be used with XREF

Underscore labels are not allowed with this directive.

LOCAL without preceding SECTION directive

A LOCAL directive was encountered outside any previously de-
fined section.

Long absolute address cannot be used

An operand was forced long where only a short or I/O short 
address was valid.

Long absolute cannot be used - force short or I/O short

A forward reference was forced long where only a short or I/
O short address was valid.

Macro cannot be redefined

A macro name cannot be used as the label for a second macro 
definition in the same source file unless the macro is defined 
and used within a declared section (see the SECTION directive, 
Chapter 6).

Macro not defined

The macro name was not found in the macro lookup table.

Macro value substitution failed

The evaluation of a macro argument expression failed.

Memory bounds greater than maximum address

The bounds argument in a LOMEM or HIMEM directive is invalid.

Memory counter designator value too large

The integer counter designator in an ORG directive is greater 
than 65535.

Memory space must be P or NONE

An END directive was encountered while the runtime memory 
space was X, Y, or L.

Missing '(' for function

All assembler built-in functions require at least one argument 
which must be enclosed in parentheses.

Missing ')' in expression

Parentheses are not balanced in an expression.

Missing argument

The argument to a DUPA or DUPC directive was not found.

Missing definition string

The substitution string for a DEFINE directive is missing.

Missing delimiter in substring

A substring construct was missing the closing square bracket.

Missing dimension

The .DIM directive had no arguments.

Missing directive name

The argument to an RDIRECT directive is missing.

Missing expression

An expression was expected by the expression evaluator.

Missing filename

No filename was provided as an argument to the INCLUDE direc-
tive.

Missing line number

No line number was provided as an argument to the .LINE di-
rective.

Missing macro name

A MACRO directive was encountered without a label or the macro 
name was omitted from a PMACRO directive.

Missing memory space specifier

One of the operands of an instruction was expected to have a 
memory space specifier (X:, Y:, L:, or P:) preceding the ad-
dress mode specifier.

Missing option

The OPT directive was specified without an argument.

Missing or illegal memory space specifier

One of the operands of an instruction was expected to have a 
memory space specifier (X:, Y:, L:, or P:) preceding the ad-
dress mode specifier.

Missing or mismatched quote

A single or double quote character was expected by the string 
parsing routines.

Missing pathname

No pathname was provided as an argument to the MACLIB direc-
tive.

Missing processor type

There was no argument provided for the -P command line option.

Missing quote
Missing quote in string

A single or double quote character was expected by the string 
parsing routines.

Missing revision

There was no argument provided for the -R command line option.

Missing section name

No section name was given as an argument to the SECTION di-
rective.

Missing size argument

No size value was given as an argument to the .SIZE directive.

Missing string after concatenation operator

The string concatenation operator (++) must be followed by an-
other quoted string.

Missing symbol name

The SYMOBJ, XDEF, and XREF directives require at least one 
symbol name as an argument.

Missing symbol value

No symbol value was given as an argument to the .VAL direc-
tive.

Missing tag for end of structure or union

A source-level debug structure or union declaration was found 
without a corresponding tag definition.

Missing tag name

No tag name was given as an argument to the .TAG directive.

Mnemonic must indicate precision using .S or .X suffix

Floating point instructions generally must indicate the pre-
cision of their operation by appending either .S for single 
precision or .X for single-extended precision.

Mode not specified

The MODE directive was not followed by either RELATIVE or AB-
SOLUTE.

Move from SSH or SSL cannot follow move to SP
Move from SSH or SSL cannot follow update to SP

A MOVE instruction using the system stack (SSH or SSL) as a 
source operand cannot immediately follow a MOVE which uses the 
stack pointer (SP) as a destination operand.

MU option must be used before any code or data generation

The MU option must be given before any data allocation direc-
tive (BSC, DC, DS, DSM, DSR) or any instruction appears in the 
source file.

Negative immediate value not allowed

The immediate count value for a DO or REP instruction cannot 
be less than zero.

Negative or empty DO loop not allowed

The loop address given in a DO instruction must specify an 
address at least one greater than the current program counter 
value.

NOGS option must be used before any section

The NOGS option must be activated before any explicit sections 
are encountered so that the assembler can use the appropriate 
counters for section relocation.

No previous function declaration

A .EF debugging directive was encountered without a corre-
sponding .BF directive.

Not enough fields specified for instruction

There were no operands specified for a MOVE, MOVEC, MOVEM, or 
MOVEP instruction.

No-update mode not allowed

The no-update register addressing mode is not allowed for this 
instruction (e.g., the LEA instruction).

Offset register number must be the same as address register number

The explicit offset register number in an operand using post-
increment, post-decrement, or indexed by offset addressing 
mode (Nn) is different from the number specified for the ad-
dress register (Rn). The offset register number may be omitted 
from these types of indirect addressing modes; the assembler 
defaults to the address register number.

Offset value greater than string size

The offset parameter in a substring construct is larger than 
the composite length of the input string argument.

Only absolute addressing allowed

The instruction allows only absolute addressing.

Only absolute and register direct addressing allowed

The instruction allows only absolute and register direct ad-
dressing.

Only immediate addressing allowed

The instruction allows an immediate source operand only.

Only immediate and register direct addressing allowed

The instruction allows only immediate and register direct ad-
dressing modes.

Only immediate and register direct and indirect addressing allowed

The instruction allows only immediate, register direct, and 
register indirect addressing modes.

Only PC-relative addressing allowed

The instruction allows only PC-relative addressing.

Only PC-relative and register direct addressing allowed

The instruction allows only PC-relative and register direct 
addressing.

Only post-increment by offset addressing allowed with LMS move

The initial data move destination operand in an LMS move must 
use post-increment by offset addressing.

Only post-increment or post-increment by offset addressing allowed

Moves to P memory allow only post-increment or post-increment 
by offset addressing.

Only register direct addressing allowed

The instruction allows only register direct addressing.

Only register direct and indirect addressing allowed

The instruction allows only register direct and indirect ad-
dressing.

Only register indirect addressing allowed

The instruction allows only register indirect addressing.

Operation not allowed with address term

Only addition and subtraction are allowed in expressions in-
volving addresses or relative terms.

Page length too small for specified top and bottom margins

The sum of the top and bottom margins specified in the PAGE 
directive is greater than the page length - 10.

Page length too small to allow default bottom margin

The bottom margin exceeds the page length specified in the 
PAGE directive.

PC-relative address too large to use short

The PC-relative offset being forced short is too large to fit 
into the instruction word.

PC-relative addressing mode not allowed

The PC-relative addressing mode is not allowed for this in-
struction.  The restriction applies, for example, to bit ma-
nipulation instructions and some jump-type instructions.

Phasing error

The value associated with a symbol has changed between pass 1 
of the assembly and pass 2. This error can occur spontaneously 
in conjunction with other errors. The assembler is designed 
to avoid phasing errors in general. If a phasing error occurs 
without any other errors this may represent an internal error 
which should be reported to Motorola.

One exception is the use of the checksumming function @CHK() 
with the EQU directive. Instruction encoding may be incomplete 
after the first pass due to forward referencing, causing the 
checksum value to change between passes. Because of this the 
SET directive must be used to assign the checksum value to a 
symbol.

Possible invalid white space between operands or arguments

The assembler verifies that fields which should not contain 
operands or values are empty. If these fields are not empty 
the assembler produces this error.

Post-decrement addressing mode not allowed

The post-decrement addressing mode is not allowed for this in-
struction. The restriction applies, for example, to bit ma-
nipulation instructions and some jump-type instructions.

Post-decrement by offset addressing mode not allowed

The post-decrement by offset addressing mode is not allowed 
for this instruction. The restriction applies, for example, 
to bit manipulation instructions and some jump-type instruc-
tions.

Post-increment addressing mode not allowed

The post-increment addressing mode is not allowed for this in-
struction. The restriction applies, for example, to bit ma-
nipulation instructions and some jump-type instructions.

Post-increment by offset addressing mode not allowed

The post-increment by offset addressing mode is not allowed 
for this instruction. The restriction applies, for example, 
to bit manipulation instructions and some jump-type instruc-
tions.

Pre-decrement addressing mode not allowed

The pre-decrement addressing mode is not allowed for this in-
struction. The restriction applies, for example, to instruc-
tions which include parallel XY memory data transfers.

RDIRECT directive not allowed in section

Since the effect of the RDIRECT directive is global, it cannot 
be used within a section which has been declared using the 
SECTION directive.  Move the RDIRECT directive outside the de-
clared section to avoid this error.

Redefinition would overflow line

A substitution string declared using the DEFINE directive will 
cause the current source line to overflow if substitution oc-
curs.

Reference outside of current buffer block
Reference outside of current overlay block

Reference was made to an underscore local label which fell 
outside the current buffer or overlay definition.

Register direct addressing not allowed

Register direct addressing mode is not allowed for this in-
struction. The restriction applies, for example, to bit ma-
nipulation instructions, some jump-type instructions, and 
parallel XY data memory moves.

Register displacement valid only with address register R2

Only address register R2 is valid as a displacement register.

Relative equate must be in same section

An EQU directive with a relative expression operand must be 
defined in the same section as the section associated with the 
operand expression.

Relative expression must be integer

A relative expression must evaluate to an integer value.

Relative expression not allowed

Relative expressions are not allowed as arguments to the as-
sembler built-in functions.

Relative SET must be in same section

A SET directive with a relative expression operand must be 
defined in the same section as the section associated with the 
operand expression.

Relative terms from different sections not allowed

Relative terms defined in different sections are not allowed 
in expressions.  This is because the relationship between the 
terms is based on where the enclosing sections are located in 
memory.

Reserved name used for symbol name

One of the DSP register names has been used as a label, oper-
and, or directive argument. These register names, in either 
upper or lower case, are reserved by the assembler. See Ap-
pendix F for a list of DSP register names.

Runtime space must be P

An instruction was encountered and the runtime memory space 
was not set to P (Program).

SCO option must be used before any label

The SCO option sends structured control statements to the ob-
ject file and thus must be specified before any symbols are 
defined in the source file.

Second data move destination accumulator same as operand destina-
tion
accumulator

The destination accumulator in a double memory read instruc-
tion is the same as the DALU accumulator specification.

Secondary opcode not allowed

The secondary opcode field is allowed only with the FMPY in-
struction.

Section not encountered on pass 1

The section declared in a SECTION directive was not encoun-
tered during the first pass of the assembler.  This situation 
indicates an internal assembler error and should be reported 
to Motorola.

SET requires label

The SET directive must have a label in order to associate the 
directive argument with a symbol name.

SET symbol names cannot be used with GLOBAL
SET symbol names cannot be used with LOCAL
SET symbol names cannot be used with XDEF

A symbol defined using the SET directive cannot be exported 
from a section using GLOBAL, LOCAL, or XDEF.

Short absolute address too large

The flagged operand value is greater than the maximum short 
address of the target DSP.

Short I/O absolute address too large
Short I/O absolute address too small

The flagged operand value is outside the I/O address range of 
the target DSP.

Short or I/O short address expected

A short or I/O short address was expected as the second oper-
and of a JCLR, JSET, JSCLR, or JSSET instruction.

Short PC-relative address too large

The flagged operand value is greater than the maximum PC-rel-
ative address of the target DSP.

SSH cannot be both source and destination register

In a MOVE instruction, the SSH register cannot be both the 
source and destination operand.

Start argument greater than machine word size

The start parameter of a @FLD() function has a value larger 
than can fit in the target machine word.

Start position greater than source string size

The start parameter in a @POS() function is larger than the 
total length of the source string argument.

Storage block size must be greater than zero

The size of a buffer allocated with the DSM, DSR, BSM, BSB, 
and other buffer directives was too small.

Storage block size out of range

The size of the buffer in a DSM, DSR, BSM, BSB, or other buffer 
directive is too large to be allocated.

Storage block too large

The runtime location counter overflowed while the assembler 
was attempting to allocate storage through a DSM or DSR di-
rective. The assembler automatically advances the program 
counter to the next valid base address given the size of the 
modulo or reverse carry buffer. This error occurs when the sum 
of the expression in the DSM or DSR directive and the runtime 
location counter value exceed available memory in the current 
memory space.

Structure or union tag mismatch

A matching tag name could not be found for the current source-
level debug structure or union declaration.

Subroutine branch to loop address not allowed

A BSR, BScc, BSSET, or BSCLR instruction cannot have as its 
target the loop address of the current DO loop.

Subroutine jump to loop address not allowed

A JSR, JScc, JSSET, or JSCLR instruction cannot have as its 
target the loop address of the current DO loop.

SVO option must be used before any code or data generation

The SVO option must be given before any data allocation di-
rective (BSC, DC, DS, DSM, DSR) or any instruction appears in 
the source file.

Symbol already defined as GLOBAL
Symbol already defined as LOCAL
Symbol already defined as XDEF
Symbol already defined as XREF

The symbol used in an GLOBAL, LOCAL, XDEF, or XREF directive 
has already been defined in a previous directive of the same 
type.

Symbol already defined as global

A symbol specified in an XDEF directive has already been de-
fined as global outside the current section.

Symbol already defined in current section

A symbol specified in an XREF directive has already been de-
fined as private within the current section.

Symbol already used as SET symbol

The label has already been used in a SET directive.  A symbol 
defined with SET cannot be redefined except through another 
SET directive.

Symbol cannot be set to new value

The label has been defined previously other than with the SET 
directive.  Only symbols defined using the SET directive may 
be redefined.

Symbol defined in current section before GLOBAL directive
Symbol defined in current section before XDEF directive

The GLOBAL or XDEF directive must appear within a section pri-
or to the definition of any symbols in its argument list.  Any 
symbols within a section which must be  accessible outside the 
section should be declared in a GLOBAL or XDEF directive im-
mediately following the SECTION directive.

Symbol name too long

Symbols are limited to 512 characters. The first character 
must be alphabetic or the underscore character (A-Z, a-z, _). 
The remaining characters must be alphanumeric, including the 
underscore character (A-Z, a-z, 0-9, _).

Symbol not previously defined

The symbol specified in an UNDEF directive was not previously 
defined in a DEFINE directive.

Symbol redefined

The symbol has already been used as a label in a previous con-
text.

Symbol tag mismatch

A matching tag reference could not be found for a tagged sym-
bol table entry.

Symbol undefined on pass 2

The symbol used as an operand or directive argument was never 
defined in the source program.

Symbols must start with alphabetic character

Symbol names must begin with an upper or lower case alphabetic 
character or the underscore character (_).

SYMOBJ symbol must be a global symbol name

Arguments to the SYMOBJ directive cannot be preceded by an 
underscore.

Syntax error - expected '):'

In an ORG directive using numeric counter designations the pa-
renthesis/colon pair separating the load or runtime address 
from the memory space, counter, or mapping characters was not 
found.

Syntax error - expected ':'

In an ORG directive the colon separating the load or runtime 
address from the memory space, counter, or mapping characters 
was not found.

Syntax error - expected '>'

The closing angle bracket in a non-local INCLUDE directive ar-
gument was not found.

Syntax error - expected comma

The comma separating operands in an instruction or directive 
was not found.

Syntax error - expected keyword BY

In a .FOR structured control statement something other than 
the optional step clause preceded by the keyword BY was en-
countered.

Syntax error - expected keyword DO

In a .WHILE structured control statement something other than 
the optional DO keyword was encountered at the end of the 
statement.

Syntax error - expected keyword TO or DOWNTO

In a .FOR structured control statement something other than 
the loop target clause preceded by the keyword TO or DOWNTO 
was encountered.

Syntax error - expected quote

The assembler was expecting the start of a quoted string.

Syntax error - extra characters

Extra characters were found after an instruction or directive 
operand.

Syntax error - invalid assignment operator

The loop assignment operator in a .FOR structured control 
statement is not an equals sign (=).

Syntax error - invalid compound operator

Structured control statement compound operators are either 
AND or OR.

Syntax error - invalid conditional operator

The conditional operator in a structure control statement ex-
pression is not valid.

Syntax error - invalid statement terminator

There were extra or invalid characters found at the end of a 
structured control statement.

Syntax error - missing address mode specifier

An instruction operand was not specified.

Syntax error - missing operand

An operand in a structured control statement expression was 
missing.

Syntax error in directive name list

A character other than a comma was found separating the argu-
ments in an RDIRECT or SYMOBJ directive name list.

Syntax error in dummy argument list

A character other than a comma was found separating the dummy 
arguments in a macro definition (MACRO directive), or a dummy 
argument began with the underscore character (_).

Syntax error in macro argument list

A character other than a comma was found separating the argu-
ments in a macro call.

Syntax error in macro name list

A character other than a comma was found separating the argu-
ments in a PMACRO directive name list.

Syntax error in symbol name list

A character other than a comma was found separating the argu-
ments in an XDEF or XREF directive name list.

Tag name not found

A matching tag name could not be found for the current source-
level debug structure or union declaration.

Too many fields specified for instruction

An instruction field that was expected to be empty contained 
data other than a comment.  This can happen when an instruc-
tion using only the X data transfer field encounters data oth-
er than a comment in the Y data transfer field.

Two dummy arguments are the same

Two dummy arguments in a macro definition (MACRO directive) 
have the same name.

UNDEF symbol must be a global symbol name

The argument to an UNDEF directive cannot be a local label, 
e.g.  a name starting with the underscore character (_).

Unexpected end of file - missing .ENDF
Unexpected end of file - missing .ENDI
Unexpected end of file - missing .ENDL
Unexpected end of file - missing .ENDW
Unexpected end of file - missing .UNTIL

The matching end-of-conditional or end-of-loop directive for 
a conditional or looping structured control statement was nev-
er found.

Unexpected end of file - missing COMMENT delimiter

The second occurrence of the delimiter character in a COMMENT 
directive was never found.

Unexpected end of file - missing ENDBUF

A BUFFER directive was encountered without a closing ENDBUF 
directive.

Unexpected end of file - missing ENDIF

An IF directive was encountered without a closing ENDIF di-
rective.

Unexpected end of file - missing ENDM

A macro definition was started using the MACRO directive, but 
the end of the source file was encountered before a closing 
ENDM directive was found.

Unexpected end of file - missing ENDSEC

A SECTION directive was found without a closing ENDSEC direc-
tive.

Unknown math error

A transcendental math function returned an error that could 
not be classified as out of range or outside the function do-
main.

Unrecognized mnemonic

A symbol in the assembler opcode field was not a defined mac-
ro, an instruction mnemonic, or a directive.

Unrecognized secondary mnemonic

A symbol in the assembler secondary opcode field was not one 
of the instructions FADD, FSUB, or FADDSUB.

.UNTIL without associated .REPEAT directive

An .UNTIL directive was encountered before a matching .REPEAT 
structured control statement.

Value argument larger than machine word size

The value parameter of a @FLD() function has a value larger 
than can fit in the target machine word.

Width argument greater than machine word size

The width parameter of a @FLD() function has a value larger 
than can fit in the target machine word.

XDEF without preceding SECTION directive
XREF without preceding SECTION directive

An XDEF or XREF directive was encountered outside any previ-
ously defined section.

XLL option must be used before any local label

The XLL option must be activated before any local labels are 
encountered so that the assembler can make the appropriate en-
tries in the symbol table.

XR option must be used before any label

The XR option must be activated before any labels are encoun-
tered so that the assembler can make the appropriate entries 
in the symbol table.

C.5	  FATAL ERRORS

<mode> encoding failure

A bad address mode indicator or register number was passed to 
the assembler encoding routines.  <mode> represents the reg-
ister set or addressing mode in question.  This is a serious 
internal error that should be reported to Motorola.

Absolute mode select failure

The mode indicator passed to the absolute addressing mode se-
lection logic was not valid.  This is a serious internal error 
that should be reported to Motorola.

Arithmetic exception

An internal floating point exception occurred while evaluat-
ing an expression.  The assembler cannot continue.

Cannot encode instruction
Cannot encode branch instruction
Cannot encode jump instruction

The correspondence between the source opcode mnemonic and the 
internal opcode type has been corrupted. This is an internal 
error that should be reported to Motorola.

Cannot seek to start of line number entries
Cannot seek to start of object data
Cannot seek to start of object file
Cannot seek to start of relocation entries
Cannot seek to start of section headers
Cannot seek to start of string table
Cannot seek to start of symbol table

An I/O error occurred which prevented the assembler from po-
sitioning correctly in the output object file.

Cannot write file header to object file
Cannot write line number entries to object file
Cannot write optional header to object file
Cannot write relocation entries to object file
Cannot write section headers to object file
Cannot write string table to object file
Cannot write symbols to object file

An I/O error occurred which prevented the assembler from writ-
ing data to the output object file.

Cannot write control string to listing file
Cannot write left margin to listing file
Cannot write new line to listing file
Cannot write new page to listing file
Cannot write page header to listing file
Cannot write string to listing file

An I/O error occurred which prevented the assembler from writ-
ing data to the output listing file.

Compare select error

The comparison indicator passed to the evaluator selection 
logic was not valid. This is a serious internal error that 
should be reported to Motorola.

Debug symbol type failure

The symbol type indicator passed to the debug selection logic 
was not valid. This is a serious internal error that should 
be reported to Motorola.

Directive select error

The directive indicator passed to the directive selection log-
ic was not valid.  This is a serious internal error that should 
be reported to Motorola.

DO stack out of sequence

The assembler maintains an internal stack representing DO loop 
nesting levels.  The internal stack pointers have been cor-
rupted.

Error in mnemonic table

The indicator passed to the instruction processing logic was 
not valid.  This is a serious internal error that should be 
reported to Motorola.

Expression operator failure

Expression operator lookup has failed. This is a serious in-
ternal error that should be reported to Motorola.

Expression stack underflow

An attempt has been made to free an expression when there are 
none to be freed. This is an internal error that should be 
reported to Motorola.

Fatal segmentation or protection fault
Contact Motorola DSP Operation

A program error has caused the assembler to access an invalid 
host system address. This generally indicates a bug in the 
assembler software.

File info out of sequence

File debug information is scrambled. This is a serious inter-
nal error that should be reported to Motorola.

File not encountered on pass 1

The file in the source input list was never processed by the 
assembler during pass 1.  This is an internal error that 
should be reported to Motorola.

Immediate mode select error

The mode indicator passed to the immediate addressing mode se-
lection logic was not valid.  This is a serious internal error 
that should be reported to Motorola.

Input mode stack out of sequence

The stack for recording whether input is from a file or a macro 
expansion has been corrupted. This is an internal error that 
should be reported to Motorola.

Invalid DO loop range check

The value passed to the end-of-DO-loop verification logic is 
bad. This is an internal error that should be reported to Mo-
torola.

Invalid instruction class

The saved MAC-type instruction class has been corrupted. This 
is an internal error that should be reported to Motorola.

Invalid tag storage class

The saved tag storage class has been corrupted. This is an 
internal error that should be reported to Motorola.

I/O error writing data word to object file

An I/O error occurred which prevented the assembler from writ-
ing data to the output object file.

Location bounds selection failure

The logic for selecting the appropriate bounds array based on 
the current memory space has returned a bad value. This is an 
internal error that should be reported to Motorola.

Option select error

The option indicator passed to the option selection logic (OPT 
directive) was not valid.  This is a serious internal error 
that should be reported to Motorola.

Out of memory - assembly aborted

There is not enough internal memory to perform dynamic storage 
allocation. Since the assembler keeps all working information 
in memory, including the symbol table and macro definitions, 
there is the possibility that memory will be exhausted if many 
symbols or macros are defined in a single assembly run.

PC-relative mode select failure

The mode indicator passed to the PC-relative addressing mode 
selection logic was not valid. This is a serious internal er-
ror that should be reported to Motorola.

Register selection failure

The register number passed to the multiply mask selection log-
ic was not valid. This is a serious internal error that should 
be reported to Motorola.

Section counter sequence failure

The ordering of location counter structures has been corrupt-
ed. This is an internal error that should be reported to Mo-
torola.

Section stack mode error

The assembler expected to restore a nested section but found 
the section list empty.  This is an internal error that should 
be reported to Motorola.

Too many lines in source file

An individual source file contained more than 2**31 lines of 
code.

Too many sections in module

There is a limit of 255 discrete sections in a given source 
file.

Unrecognized transformation mnemonic

The lookup of an FADD or FSUB secondary operand failed. This 
is an internal error that should be reported to Motorola.


Appendix D

ASSEMBLER LISTING FILE FORMAT

D.1	  INTRODUCTION

The assembler always produces a source listing file unless the com-
mand line option -OIL (inhibit listing) is specified. See Chapter 
1, RUNNING THE ASSEMBLER, and the OPT directive in Chapter 6 for 
more information on command line and listing options. If the -L 
command line option is given, the listing goes to the file named 
as the option argument; if no argument is specified, the listing 
file takes the name of the first source file on the command line 
and changes the extension to .LST (see Chapter 1). If the -L option 
is omitted, the listing is routed to the standard output, which in 
most cases is the console or user terminal by default. Most of the 
operating systems which host the assembler support I/O redirection, 
so that the standard output may be redirected to an arbitrary des-
tination (printer, file, null device, etc.).

D.2	  LISTING FILE COMMENTARY

Figure D-1 is an assembler-generated listing of a program employing 
a 16-point Decimation in Time Fast Fourier Transform (FFT) routine 
implemented as a macro. The listing illustrates a selection of the 
format features offered by the assembler. The following section 
highlights some of those features.

At the top of every listing page is a banner which identifies the 
assembler and lists its version number, the date and time of as-
sembly, the current input file name, and the page number. Following 
the banner on pages other than the first would appear any titles 
or subtitles specified using the TITLE and STITLE directives, re-
spectively.

On line 1 of this particular program an OPT directive specifies 
data value expansion of declared constants (CEX), cross-referenc-
ing of both local and global symbol names (LOC and CRE), and gen-
eration of memory utilization reports at the end of the listing 
(MU). The format of cross-reference and memory utilization reports 
is discussed in later sections.

On line 2 a PAGE directive specifies the page dimensions.  Note 
that line 3 is missing.  In the source file there is a TITLE di-
rective on line 3; TITLE and STITLE directives do not appear in the 
listing file.  The title itself does not appear until the next page 
of the listing.

A MACLIB directive declares a macro library path on line 5.  The 
significance of this to the appearance of the listing will be dis-
cussed shortly.  The comment lines following (and all lines) have 
been shifted right to make room for line numbers and constant or 
data value displays, as for example with the group of equates be-
ginning on line 12.

On line 19 an INCLUDE directive causes the source input to be 
switched to a file named SIN16.ASM in the FFTLIB subdirectory. This 
usage of INCLUDE is provided for illustrative purposes, since the 
previous MACLIB declaration makes it unnecessary. By line 20 the 
input stream has changed to the new file; the first line of the new 
file is the definition line for a macro that will initialize the 
FFT sine and cosine tables in X and Y memory. Notice the lower case 
`m' to the right of the line number on line 21 and following. This 
indicates that a macro definition is in progress; the lines are not 
assembled but are retained for macro expansion later.

At line 41 the ENDM directive is encountered, as well as the end 
of the included macro file. The source input reverts to the orig-
inal file, the next line of which is an invocation of the macro 
(SIN16) just defined. Since the MEX option was not specified, the 
macro expansion does not appear in the listing. However, on the 
next non-empty source line, the OPT directive is used again to turn 
on printing of macro expansions and turn off the display of macro 
definitions (NOMD).

Line 68 of the listing contains an ORG directive which sets up the 
initial value of the runtime location counter to $200. The memory 
space and counter value are shown to the right of the line number 
column. If an overlay had been defined here (see Chapter 4), the 
load memory space and location counter would appear to the right 
of the runtime space and counter value. The line numbers then skip 
to line 151 which contains a call to the macro DITFFT. The macro 
was not defined in this source file but its definition was read 
from an external file in a macro library directory as specified by 
the prior MACLIB directive. The skipped line numbers represent that 
definition, which does not appear due to the previously given NOMD 
option.

Line 203 illustrates several listing features of the assembler. The 
plus sign (+) to the right of the line number column indicates a 
macro expansion in progress. The next field is the memory space and 
location counter value, followed by the encoded instruction. The 
mnemonic and operand fields are spread out for easier reading. The 
`00000227' by itself on line 204 is the loop address for the DO 
loop; it is stored in the second instruction word and represents 
one less than the address of the label _end_pass.

On page 7 there are two errors reported in the listing.  Error mes-
sages contain the listing line number, the source file name and the 
source line number where the error occurred, a severity level 
(WARNING, ERROR, or FATAL), and the message text.  In addition, the 
error message may contain extra information indicating erroneous 
symbols or the field (Label, Opcode, Operand, Opcode 2, Operand 2, 
X Move, Y Move) where the error occurred.  Page 8 is the end of the 
source statement listing.  After the END directive at line 232, the 
assembler reports the total number of errors and warnings it en-
countered during the assembly process.  

After the source listing, the assembler records other information 
encountered during assembly.  On page 9 the names of the two macros 
used in the program are listed, along with their definition lines 
in the source listing.  If any sections had been declared in the 
program they would be shown here, as well as define symbols and 
their corresponding substitution strings.  Next the symbol table 
is output, sorted by symbol name.  The symbol table data includes 
the symbol type (integer, floating point), its value, the section 
where it was defined if applicable, and any attributes it may have 
(LOCAL, GLOBAL, SET).

Figure D-3 contains an annotated assembler listing line showing 
virtually every possible listing field. The significance of some 
fields may require further explanation. The macro definition/ex-
pansion column will contain a plus sign (+) during macro expansion. 
It will contain a lower case `m' during macro definition, and a 
lower case `d' during data constant expansion (the CEX option used 
with the DC directive). When a nested macro is expanded, this col-
umn will contain both a lower case `m' and a plus sign. A lower 
case `i' in this column indicates that the line has been skipped 
as a result of an IF-THEN-ELSE directive sequence. A lower case `p' 
means that the line was automatically generated by the assembler, 
ordinarily to introduce pipeline delay.

D.3	  CROSS-REFERENCE FORMAT

The assembler will optionally generate a cross-reference listing 
of all symbols used in the source program. This can be done by using 
the CEX option of the OPT directive (Chapter 6). The cross-refer-
ence listing for the above sample program is shown in Figure D-2. 
It contains a sorted table of symbols, each one followed by a list 
of line numbers in the source listing where a reference to the sym-
bol occurred. Line numbers followed by an asterisk (*) indicate the 
line where the symbol was defined.

D.4	  MEMORY UTILIZATION REPORT FORMAT

The assembler can optionally record and report allocation and usage 
of the separate memory spaces of the target DSP.  This is done with 
the MU option of the OPT directive (Chapter 6).  A memory utiliza-
tion report is a memory map showing data allocation, code genera-
tion, and unused memory areas along with associated label, section, 
and overlay information, if available.

Figure D-4 shows the memory utilization report for the assembler 
source in Figure D-5. The individual X, Y, L, and P memory spaces 
are reported separately. The starting and ending addresses, length, 
type, and any label, section, or overlay data are display for each 
reported block. The blocks are delimited by the occurrence in the 
source of either a data allocation directive (BSC, DC, DS, DSM, 
DSR) or an ORG directive.

In the X memory report of Figure D-4 the first reported block is 
an uninitialized area of 1024 words. This corresponds to the first 
DS directive in Figure D-5, which reserves 1024 words of memory in 
X data space. The next block of memory in X data space is the over-
lay code for the FIR filter. It begins immediately after the first 
block and is ten words long.

The type column shows what kind of code or data has been generated, 
as well as indicating that a block is unused.  In the line corre-
sponding to the first DS directive in the source, the type is DATA 
to indicate that it is an uninitialized data area.  There are other 
types for initialized data, code, and modulo and reverse carry 
buffers.  For example, the second block in the X memory report is 
of type CODE because it is overlay code to be executed in P memory.

The label from the source file is included on the report under the 
label column, since there was a label associated with the DS di-
rective.  If there had been no label, the label column on the report 
would have been blank.  The section and overlay address columns are 
empty because there is no current section and no overlay in 
progress at this point in the source.

In the next-to-last line of the X memory report (start address 
$400), there is an entry of type CODE with an overlay address. This 
is the corresponding load entry for the first line in the P memory 
report, and indicates that this is an overlay block. Separate re-
port records are generated as a result of the ORG directive in the 
source which has the form ORG P:,X:$400, signifying an overlay. In 
the X memory report, the overlay address is P:0 and the R in pa-
rentheses means that the overlay address is the runtime address. 
Conversely, the first line in the P memory report shows an overlay 
address of X:400; the L in parentheses means that the overlay ad-
dress is the load time address.


Appendix G

HOST-DEPENDENT INFORMATION

G.1	  INTRODUCTION

The Motorola DSP development software runs on several host machine 
and operating system platforms.  The following sections give in-
formation on hardware requirements, installation, and other topics 
relating to specific host environments.  The descriptions below re-
fer directly to the DSP assembler, but the sections on hardware 
requirements and installation apply similarly to the DSP linker and 
librarian as well.  See the appropriate chapters in the DSP Linker/
Librarian Reference Manual for more information on invocation op-
tions and processing of these utilities.

G.2	  DOS/386 ENVIRONMENT

The Motorola DSP assembler is delivered as an executable file on a 
high density 3 1/2" diskette. It may be run from either a floppy 
drive or a hard disk, although a hard disk is recommended. The as-
sembler will make use of extended memory if it is present, and will 
utilize available disk space if physical memory is exhausted.

G.2.1	  Hardware Requirements

The minimum hardware requirements for the assembler in the DOS/386 
environment include:

386-based PC or compatible with 80386 (or higher) CPU, 4MB of 
RAM, and one 3 1/2" HD diskette drive.

MS-DOS v3.0 or later.

Since the assembler uses all of available memory for storage of 
symbols and macros, the optimal system configuration would have at 
least 4 megabytes of extended memory. The assembler will make use 
of extended memory beyond 640K and may even use a virtual memory 
disk file if necessary. A utility called PMINFO is supplied to pro-
vide memory region tuning and virtual file sizing for systems run-
ning under Microsoft Windows or other DOS extended memory managers.

G.2.2	  Installation

Make a backup copy of the installation diskette using the DOS DIS-
KCOPY command.  For example, if the installation diskette is in 
drive A and a blank disk is in drive B, issue the following command:

DISKCOPY  A:  B:

Put the distribution diskette in a safe place as a backup.

If the INSTALL.EXE program is present on the distribution disk it 
can be used to install the assembler software.  Insert the diskette 
into drive A and enter the following command:

A:INSTALL

The install program will then query for information about the host 
system and where the software should be placed.

If there is no installation program, create a directory where the 
assembler can reside and copy the executable file into it.  For 
example, if a directory has been created called BIN which holds all 
executable files on the hard disk, and the hard disk is the current 
logged disk, the following command will copy the assembler from the 
installation diskette in drive A to that directory:

COPY  A:ASM56000.EXE  \BIN

Again, keep the assembler distribution diskette in a safe place as 
a backup.

G.2.3	  Source File Text

Input to the assembler should be in a standard ASCII text file with 
carriage return/line feed character pairs as line terminators. This 
type of file is created by most standard text editing programs used 
on 386 PCs, such as the DOS-supplied editor EDIT.

Using word processing packages for creating assembler input source 
files is a little more involved, but can certainly be done. Word 
processing packages use special character encodings to indicate 
format and font settings, margins, indentation, and so forth. In 
some cases these special encodings violate the input requirements 
of the assembler, and must be removed or changed.

Most word processing programs have a facility for converting in-
ternal-format documents to standard ASCII text files. See Chapter 
2, INPUT FILE FORMAT, for more information on the form and content 
of assembler input files.

G.2.4	  Invoking the Assembler

The assembler is invoked from the DOS command line by entering the 
name of the assembler executable without the extension, followed 
by any desired options, and finally the names of the source files 
to be assembled.  See Chapter 1, RUNNING THE ASSEMBLER, for a list 
of options which can be included on the command line.

As an example, if the assembler diskette was loaded in drive A, and 
the source file was located on the disk in drive B, the following 
command at the DOS prompt would assemble the file MYFILE.ASM, put-
ting the object file MYFILE.CLN and the listing file OUTFILE.LST 
onto the disk in drive B as output:

A:ASM56000  -Bb:myfile.cln  -Lb:outfile.lst  b:myfile

Since DOS supports standard input and output channels, in the ex-
ample above any warning or error messages would appear both in the 
listing file and on the standard output (by default the console 
screen).

DOS also supports I/O redirection, so that the assembler listing 
can be sent to a file or directly to an output device.  Given a 
hard disk environment where the assembler executable has been load-
ed into a directory BIN that is in the program search path, the 
following command will assemble the source file FFT.ASM and send 
the listing output directly to the Line Printer 1 device:

ASM56000  fft.dsp  >LPT1:

In this example no object file is created and all errors and warn-
ings are sent to LPT1: (e.g. they do not appear on the console 
screen).  The input file is assumed to be in the current directory.  
See the IBM or Microsoft DOS manual for more information on direc-
tory structure, I/O redirection, and command paths.
Notation

The notational conventions used in this manual are:

DIRECTIVE

All assembler mnemonics and directives are shown in bold upper 
case to highlight them. However, the assembler will recognize 
both upper and lower case for mnemonics and directives.

{ }

Contains a list of elements or directives, one of which must 
be selected. Each choice will be separated by a vertical bar.  
For example, {R I L} indicates that either R or L must be se-
lected.

[ ]

Contains one or more optional elements. If more than one op-
tional element is shown, the required element separators are 
indicated.  All elements outside of the angle brackets (< >) 
must be specified as they appear.  For example, the syntacti-
cal element [<number>,] requires the comma to be specified if 
the optional element <number> is selected.

< >

The element names are printed in lower case and contained in 
angle brackets.  Some common elements used to describe direc-
tives are:

<comment>			A statement comment

<label>			A statement label

<expr> or			An assembler expression
<expression>

<number>			A numeric constant

<string>			A string of ASCII characters enclosed in 
quotes

<delimiter>			A delimiter character

<option>			An assembler option

<sym> or			An assembler symbol
<symbol>



Supporting Publications

DSP56000 Family Manual. Motorola, Inc. 1992.

DSP56002 User's Manual. Motorola, Inc. 1993.

Motorola DSP Simulator Reference Manual. Motorola, Inc. 1994.

Motorola DSP Linker/Librarian Reference Manual. Motorola, Inc. 
1994.
Preface
