Notes on New Features
Motorola DSP Assembler, Linker, Librarian
04/10/90


* Assembler/Linker Command Line Format

The assembler and linker command line processing has been modified to
support optional white space between command options and arguments.
It is no longer necessary to append the option argument immediately
after the option letter.  So for example the following assembler line:

        asm56000 -bfilter -l -omu,cex main fir io

could be written equivalently as:

        asm56000 -b filter -l -o mu,cex main fir io

An ambiguity arises when the final option on the command line (before
the list of file names) is an option that takes an optional argument:

        asm56000 -b filter -l main fir io

In the example above it is not apparent whether MAIN refers to a
listing file name or to a source file name.  In the absence of any
clear delineation the assembler and linker will assume that it is an
input file and will attempt to open the file for reading.  In order to
explicitly state that a file name in this position is to be regarded
as an option argument, the option list may be separated by the list of
file names by a double dash sequence:

        asm56000 -b filter -l listing -- main fir io

Alternatively the command line can be rearranged such that options
with optional arguments do not appear immediately before the file name
list.

Any output file can be redirected to the standard output by following
the appropriate command line option by a dash.  For example, to route
the assembler object file to standard output and write the listing
file to a file with the same filename as the source the command would
look like:

	asm56000 -b - -l fir io

Note that redirecting all output to the standard output can yield
unpredictable results.

The assembler no longer requires quotes around DEFINE values on the
command line.  Thus the following command line option:

        -d FOO boo

is the same as the following assembly language source statement:

        define FOO 'boo'

Define values on the command line which do contain embedded quotes are
processed as before.


* Assembler/Linker Environment Variables

The assembler and linker now support extension of the command line via
environment variables (if supported on the host).  The assembler
environment variable is DSPASMOPT; the linker variable is DSPLNKOPT.
Given the following SET command in an MS-DOS system:

        set DSPASM=-a -o mu,cex

the assembler command below:

        asm96000 foobaz

is equivalent to:

        asm96000 -a -o mu,cex foobaz

Note that if the environment variables are set they are used
unconditionally for every invocation of the assembler or linker.
There is no check for duplicate or inconsistent command line options.


* Assembler/Linker Command File

A new linker and assembler command line option allows placing of
command line arguments and file names into a separate file for
parsing.  This is useful in host environments where the length of the
command line is restricted.  The syntax of the option is:

        -f<cmdfile>

where <cmdfile> is a text file containing options, arguments, and file
names to be passed to the linker or assembler.  The arguments in the
file need only be separated 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.


* Assembler Processor Revision Option

The -R assembler command line option allows the programmer to specify
which processor revisions are to be EXCLUDED from the assembly.  For
example, if the following command were given:

	asm56000 -rc myprog

The file MYPROG.ASM would be assembled WITHOUT the DSP56000 Revision C
enhancements.  This means that the assembler would generate errors if
MYPROG.ASM contained any LMS moves or bit manipulation instructions on
registers.


* Assembler/Linker Verbose Option

The assembler and linker both now feature a verbose mode, activated
with the -V command line option.  This option causes the assembler and
linker to report beginning of passes, opening and closing of files,
and other information to insure that processing is proceeding normally.


* New/Expanded Assembler Functions

There is a new assembler function RND which returns a random floating
point value in the range 0.0 to 1.0.

The MIN and MAX functions now support an arbitrary number of arguments
(e.g.  @MIN(-1.0,5.2,-99.99,2.34) will return -99.99).

The FRC/LFR and UNF/LUN functions have been enhanced to perform
conversions between native machine values and floating point numbers.
FRC takes a floating point number and converts it to a fixed point
fraction on fractional machines; on floating point machines it returns
the bit representation of the floating point value.  LFR does the same
thing for long values.  UNF accepts a fixed point fractional value (or
a bit representation on floating point machines) and converts it to a
floating point number.  LUN performs the corresponding conversion on
long values.

The CCC function returns the cumulative cycle count as an integer; it
can be used in conjunction with the CC, NOCC, and CONTCC options.  The
CTR function returns the counter type (default, low, high) for the
runtime or load location counter.

There are two new macro-oriented functions.  CNT returns as an integer
the number of macro arguments provided for the current macro expansion
(empty arguments are still counted but not missing ones).  The ARG
function returns an integer 1 if the referenced argument is present, 0
otherwise.  ARG takes one argument, either an expression or a
singly-quoted symbol name.  If the argument is quoted, it is looked up
as a macro dummy argument to determine if the corresponding actual
argument was present in the macro call.  If the argument to ARG is an
expression it is taken as an integer ordinal for the desired macro
dummy argument.


* Expanded Macro Value Substitution

Values substituted in macros via the ? or % operators may now be
substituted with a range up to the word size of the target processor.
Floating point values may be substituted as well.  If a floating point
value is substituted via the ? operator the resulting number will be
output in decimal notation.  If substitution occurs with the %
operator on a floating point value, the value will be converted to
binary fractional with appropriate saturation for fractional targets
and to the floating point bit representation for floating point
targets and output in hexadecimal notation.


* New Assembler Options

There is a new option IC that will cause the assembler to ignore case
in label, section, and DEFINE directive names.  The option must be
specified before any symbols are defined.  The linker has a
corresponding -n command line option which makes it case-insensitive
as well.

The SCL option causes labels generated by structured control
statements (SCS) to be ignored when checking local (underscore) label
scope.  This means that if a local label follows an SCS block it will
still be recognized within the block even though a non-local SCS label
appeared between the local label reference and its definition.


* BSR Directive Renamed to BSB

The BSR (Block Storage Reverse) was renamed to BSB (Block Storage
Bit-reverse) to avoid a name conflict with the DSP96000 BSR (Branch
to Subroutine) instruction.  DSP56000 programmers may continue to use
BSR as a synonym for the BSB directive.


* New Assembler TABS Directive

The TABS directive allows the programmer to set the tab expansion
width on assembler-interpreted source (the default is 8 spaces).  This
is useful when the NOPP option is specified to obtain a vanilla
listing such that the orginal source tab stops are maintained.


* Symbol Scoping in Nested Sections

Previously, nesting assembly language sections provided nothing more
than a mechanism for arranging code.  There was no symbol scoping as
is implied in some higher level language uses of nesting.  Now the
assembler is able to accomodate symbol scoping within nested sections.
This means that 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.  The scoping behavior can be turned
off and on with the NONS and NS options respectively.  Note that the
nesting functionality does not affect independent relocation of the
section.  A nested section can be relocated in conjunction with the
surrounding section by use of the STATIC modifier on the SECTION
directive (see below).


* New SECTION Directive Modifiers

The assembler SECTION directive has been changed to allow for either
of two modifiers to be appended to the directive line:

        SECTION <NAME>  [<GLOBAL>|<STATIC>]

The STATIC modifier indicates that the section is not independently
relocatable; that is, it is relocated in terms of its enclosing
section.  The GLOBAL modifier means that all symbols defined inside
the section are global; it is as if every symbol defined in the
section were declared global.  Put another way, the GLOBAL modifier
disables a section's data hiding ability; the STATIC modifier disables
a section's independent relocatability.


* New LOCAL/GLOBAL Directives; Change in XDEF/XREF Functionality

The LOCAL directive is used to make a forward declaration of a local
symbol inside a section.  This is useful when 1) a section is nested
within another section, 2) there is a symbol with the same name in
each section, and 3) there is a forward reference to the symbol in the
nested section.  For example, consider the following code fragment:

	section	foo
label
	...
	section	bar
	local	label
	move	#label,r0
label
	endsec

	endsec

Without the LOCAL directive in the BAR section the assembler would get
confused between passes as to which LABEL value should be used in the
MOVE statement (assuming nesting resolution was active).

The GLOBAL directive is equivalent to using XDEF with the XR option
active.  In other words, a symbol declared as GLOBAL within a section
will literally be global, e.g. recognized as such within and outside
of any other section.

The XDEF/XREF directives are now more restrictive so that their
relationship is more meaningful.  By default if a symbol is XDEFed
within a section it will only be visible within its own section and
within sections that explicitly XREF it (e.g. it will not
automatically be visible outside of any section).  If it is necessary
for the symbol to be visible outside of any section then use the
GLOBAL directive or the XR option.


* New HIMEM/LOMEM Directives

Two new assembler directives provide for setting high and low memory
bounds:

        <HI|LO>MEM   <mem>[...<mem>]

        where:
                mem = <spc>[<ctr>][<rl>]:<val>
                spc = X | Y | L | P     (Memory space)
                ctr = L | H             (Counter specifier)
                rl  = R | L             (Run/load)
                val = absolute expression indicating high/low limit

The specified limit is checked on each counter increment or reset (via
the ORG directive).  A warning is issued if the counter exceeds the
limits as given in the directive argument.


* Separate Absolute Counters

When the assembler operated in relative mode but generated absolute
code only a single global set of absolute counters was used.  This
made switching among absolute sections in relative mode a messy
proposition.  The GS/NOGS options provide a measure of control in this
situation.  The GS option makes all sections global static, meaning
all section counters and attributes will be associated with the GLOBAL
section (as absolute counters had previously been handled).  The NOGS
option gives each section its own set of absolute counters, just as it
does with relocatable counters.  This makes switching among absolute
sections easier, and is now the default in relative mode.


* Assembler Floating Labels, Pretty Printing, and Syntax Alternatives

Labels may now be indented by appending a colon (:) to the end of the
label name.  There can be no intervening spaces or tabs between the
label name and the colon.  This works for both normal and local
(underscore) labels.  Labels still will be placed in the first column
of the listing file unless the NOPP (no pretty print) option is given
via the OPT directive (see below).

If the NOPP option is specified to the assembler, no special listing
file formatting will occur.  The assembler will generate line numbers,
location counter values, and cycle counts, then output the source line
essentially as it was encountered in the input file (tabs are still
converted to spaces).  The assembler performs no field alignment, but
indented labels and previously aligned comments in the source remain
intact.  Page headings and title lines are still produced.  The NOPP
option must be given explicitly; pretty-printing is the default
behavior.

An alternative syntax for DEFINE and SECTION directives has been
introduced.  The usual syntax for these directives is:

        DEFINE  foo     'bar'
        SECTION foo

The alternative is to place the directive name in the label field:

foo     DEFINE  'bar'
foo     SECTION

There is no functional difference in using the alternate mode of
syntax.


* Relocatable Buffers and Overlays

There are three new buffer allocation directives.  BADDR takes a
buffer type (M for modulo, R for reverse-carry) and a buffer size and
sets the program counter to the start of the buffer (as opposed to
setting it beyond the buffer as the DSM/DSR directives do).  BSM and
BSR are simply block-initialization versions of DSM and DSR: they
accept a buffer size and value, then adjust the program counter
according to the size and initialize memory based on the supplied
value.

Modulo/bit-reverse buffers and overlays are now fully relocatable.
Two new assembler directives, BUFFER and ENDBUF, facilitate the use of
data definition directives for buffer initialization and control.  The
BUFFER directive takes a buffer type and size, then allows for any
combination of DC, BSC, and DS directives to establish the initial
content of the buffer.

Overlay code is relocatable with respect to a specific relative
address.  The assembler syntax for specifying a relocatable overlay is
as follows:

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

        rms   - runtime memory space
        rlc   - runtime location counter
        rmp   - runtime physical mapping
        exp   - relocatable runtime base
        lms   - load memory space
        llc   - load location counter
        lmp   - load physical mapping

If <exp> is a relative expression, the assembler guarantees that
labels in the overlay block will be based from <exp>; this value is
resolved at link time.


* Location Counter Defaults and Resetting

In previous versions of the assembler the runtime location counter was
used as the default counter when both runtime and load counters were
the same (e.g. when no overlay was in progress).  This caused some
problems in code where a group of overlay blocks were intended to be
loaded contiguously immediately after a code block that established
the load address.  Consider the following code fragment:

	ORG	P:$200
	NOP
	ORG	P:$40,P:
FOO	NOP
	ORG	P:$40,P:
BAR	NOP
	ORG	P:
BAZ	NOP

Formerly the symbol FOO would load at address P:0 with a value of $40.
This is because the load counter, which is defaulted in this case, was
never initialized (e.g. only the runtime counter was really
initialized to $200 in the first ORG statement).  Currently the symbol
FOO would load at P:$201 with a value of $40, since now it is the load
counter that is set in the initial ORG.  Similarly, BAR would load at
P:$202 with value $40.  The final ORG defaults back to the load
counter and is loaded at P:$203 with value $203.


* Incremental Linking

The linker now supports a form of incremental linking whereby several
link files can be combined into one link file for subsequent
processing.  This capability is useful for combining modules which
have already been debugged into a single tested unit.  The -i command
line option causes the linker to produce a .lnk file instead of an
absolute load file.


* Unresolved References via Command Line

The linker -u option allows the programmer to declare an unresolved
reference from the command line.  This is useful for forcing an
undefined external reference in order to link entirely from a library.


* Enhanced Relocation

The linker is now somewhat smarter about code placement at fixup time.
It generates an internal memory map of all memory spaces and uses the
map to determine where code and data blocks should be located.  First,
it maps all absolute sections and sections which have been explicitly
located via the link control file SECTION directive.  Next, it handles
ordered sections (see below), followed by relocation of normal section
blocks.  Finally, all non-overlay symbols are fixed up so that overlay
blocks can be adjusted and overlay symbols resolved.


* Extended Code Placement Options

Directives in the link control (formerly memory) file have been
added/extended/enhanced to provide greater control over code placement
and memory layout.  The SECTION directive has been extended to provide
implicit ordering when an absolute address expression is omitted from
the directive syntax.  Consider the following example:

section foo     p:0
section bar     p:
section baz     p:

The P memory code and data for section FOO will be based at absolute
address zero.  The P memory code and data for section bar will be
placed at the lowest available P memory address after the code for
section foo and any other sections with absolute code or data
allocated in P memory.  This will be followed by the P code and data
for section baz, after which all other section code and data will be
located in command line order.

The SECSIZE directive allows for setting the size of a section for
padding purposes.  The size of a given memory space may be given in
terms of an expression whose value is an absolute integer or a
floating point expression representing the percentage of padding
desired.  For example, SECSIZE BAZ Y:$400 sets aside 1K words for Y
memory in section BAZ; SECSIZE BUZZ XH:150.0 always sets aside one and
one-half times the actual memory requirements for the X high memory
allocation of section BUZZ.

Unnamed memory blocks can be reserved by using the RESERVE directive
in the control file.  The statement RESERVE P:0..$1FF reserves the
first 512 locations in P default memory.  A high memory limit (for
reflecting physical system limitations) can be established with the
MEMORY directive.  MEMORY X:$FFFF,Y:$FFFF sets the default memory
bounds for X and Y to 64K.  A linked module can be renamed through use
of the IDENT directive.  This is similar to the assembler IDENT
directive, where IDENT FUNK 2 1 identifies the module named FUNK with
version number 2 and revision 1.  This information is written to the
object file START record, and is useful for renaming incrementally
linked module to something other than the first module linked.


* Library Path Option

The linker command line -P option may be used to specify an optional
library path in which to look for library files.  Ordinarily when the
linker encounters a -L option followed by a library filename, it looks
for the library in the current directory only (or in the path supplied
as part of the library specification).  If the -P option is given the
linker appends the string supplied with the -P to the library filename
and attempts to open the library again.  The -P option may be
specified as many times as desired.


* Linker Map File Options

The linker has a new record type which may be included in the .mem
file to control the format of the .map file.  The MAP PAGE record
works similarly to the assembler PAGE directive, and causes the .map
file to be printed on the page according to the parameters supplied.
For example, the following MAP PAGE indicates a column width of 132, a
physical page length of 66 lines (default), with three blank lines at
the top and bottom of each page:

        MAP     PAGE    132,,3,3

The MAP OPT record determines the content of the output in the linker
map file.  The following MAP OPT options are available:

        NOCONST         - do not list symbols without a memory space
                          attribute
        NOLOCAL         - do not list non-global symbols (e.g. symbols
                          which are local to a section)
        NOSECADDR       - do not list sections by address
        NOSECNAME       - do not list sections by name
        NOSYMNAME       - do not list symbols by name
        NOSYMVAL        - do not list symbols by value

The following MAP OPT record specifies no constants in the map
listing, as well as no listing of symbols by value:

        MAP     OPT     NOCONST,NOSYMVAL

The MAP OPT record may appear as many times as necessary in the .mem
file.  If a .map file is requested on the command line and there are
no MAP OPT records in the .mem file (or there is no .mem file), the
linker lists all symbols and sections by name, address, and value as
in previous versions.


* Linker Symbol Output

The linker will now send symbol information to the load file, either
by using the command line -S option to dump all symbols or the memory
control file SYMOBJ directive to selectively obtain symbol
information.  If the -S option is given the linker writes a _SYMBOL
record for every symbol in the linker symbol table.  This is similar
to the way the SO option works in the assembler absolute mode.  If the
SYMOBJ directive is used only those symbols given in the directive
list will be sent to the load file.  The syntax for the SYMOBJ record
in the memory control file is as follows:

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

Section is the name of the section containing the definition of the
symbols that follow.  If the symbols are not in any section then
"GLOBAL" should be specified here.  The symbols are then listed,
separated by commas (no intervening white space).  If the section or
symbols are not found an error is issued.


* Librarian Interactive Mode

The librarian now has an interactive mode.  When the librarian is
invoked without any arguments (or with the /COMMAND qualifier under
VMS DCL) it displays a '>' prompt and waits for input.  Entering
'HELP' followed by a carriage return will make the librarian display a
list of commands.  The syntax is much like the command line syntax;
the commands may be spelled out and the library must always be
specified, but it is quicker than reloading the librarian every time
an operation is needed.


* Change in Assembler/Linker Expression Operator Precedence

The precedence for operators in arithmetic expressions has been
changed.  The operators were borrowed from the C language but the
precedence rules were not; this change has been made to cause the
assembler/linker operator precedence rules to more closely track C
precedence rules.  The new operator precedence hierarchy is as
follows:

1. parentheses
2. unary plus, unary minus, one's complement, logical negation
3. multiplication, division, mod
4. addition, subtraction
5. shift
6. less than, less than or equal to,
   greater than, greater than or equal to
7. equal, not equal
8. bitwise and, or, eor
9. logical and, or

As before, operators of the same precedence are evaluated left to
right.


* Changes to Link and Load File Formats

There have been a number of changes made to the link file format and
minor changes to the load file format.  In the latter case
specifically the START record was extended to provide target machine
type data.  More information is available in Appendices E and F of the
MOTOROLA DSP ASSEMBLER REFERENCE MANUAL.
