
  a56 - a DSP56001 assembler - version 1.2

/*
 * Copyright (C) 1990-1994 Quinn C. Jensen
 *
 * Permission to use, copy, modify, distribute, and sell this software
 * and its documentation for any purpose is hereby granted without fee,
 * provided that the above copyright notice appear in all copies and
 * that both that copyright notice and this permission notice appear
 * in supporting documentation.  The author makes no representations
 * about the suitability of this software for any purpose.  It is
 * provided "as is" without express or implied warranty.
 *
 */

V1.2 CHANGES

Contributors to V1.2 -

    Andreas Gustafsson <gson@joker.cs.hut.fi>
      - Added DS and DSM directives
      - Generalization of the use of "*" allowing current program counter
        to be used in any expression (including "org l:*" which is useful
        for changing spaces without changing the PC)
      - Noted a bug with MOVEP to a non-symbolic I/O address.  I believe
        this is now fixed.
      - Noted that mispelled argumentless operators will be treated as
        labels.  For example, N0P (N-zero-P) will be treated as a label.
        Unfortunately, my own use of a56 (i.e. using cpp as the macro
        pre-processor) complicates this.  However, the grammar might
        have been simpler if the lexical analyzer was able to distinguish
        between label declarations and references instead of leaving that
        up to the YACC parser.

    Tim Channon <tchannon@black.demon.co.uk> and Peter Breuer
      <ptb@comlab.ox.ac.uk>
      - Missing ";" in grammar!

    Rober Ganter <ganter@ifi.unibas.ch>
      - Fixed bad comment on line 10 of a56.y

    Me <jensenq@zdomain.com>
      - Listing now includes psect usage summary
      - Better checking of movec arguments
      - Added int(value) function to convert floating point constant expression
        to integer (by truncation)
      - Correctly convert a floating -1.0 to 0x800000
      - Wrote a new lexical analyzer and lexical parser generator
      - Many other minor enhancements and fixes.
      - Ported to DOS using DJ Delories' GCC port.  (Tools available at
        ftp://omnigate.clarkson.edu/pub/msdos/djgpp)

Known bugs/deficiencies:

        - MOVE to a control reg generates bogus code (always use MOVEC,
          MOVEM, and MOVEP)

The example code this time around includes a full six-comb stereo reverb
(based on Moorer).  This one sounds a lot better than the four-comb algorithm.
Each comb uses a one-pole low-pass filter in the loop.  It lacks the
early-reflection FIR (although Motorola's rvb2.asm has it) but has
true stereo decorrelation by using a twin allpass stage.  My old reverb
just used inversion to simulate stereo (the whole reverb effect would
disappear if you mixed the outputs).  I've included only actual reverb
code itself.  It lacks the hardware-implementation-specific shell.


---------------------------------------------------------------------------

OVERVIEW

This program was written as a vehicle to learn the intricacies
of the DSP56001 instruction set, and to provide a tool for Unix-based
DSP code development (for those of us without a NeXT machine.)

The intent was to provide compatibility with Motorola assembler's syntax.
But since the author did not have Motorola's assembler or its documentation,
it is no doubt far from compatible.  Only a few pseudo-ops are implemented--
probably only partially.

Macros are not supported, except through the use of an external macro
preprocessor, such as /lib/cpp.  To facilitate cpp macro expansion, multiple
assembler statements on a single input line are delimited with an '@', e.g.:

        #define JCHEQ(c,label)	move #c,x0 @cmp x0,a @jeq label

        #define JCHNE(c,label)	move #c,x0 @cmp x0,a @jne label


SUPPORTED PSEUDO-OPS

The following is a list of the pseudo-ops that are recognized:

        <symbol> = <expression>                         ;assign a symbol
        <label> EQU <expression>                        ;ditto

        ALIGN <number>                                  ;set location pointer
                                                        ;to next integral
                                                        ;multiple of <number>

        ORG <space:> <expression>                       ;new location pointer
        ORG <space:> <expression>, <space:> <expression>

        DC <dc_list>                                    ;declare constants

        DS <number>                                     ;reserve <number>
                                                        ;words of space

        <label> DSM <number>                            ;reserve space for
                                                        ;properly aligned
                                                        ;modulo-addressed
                                                        ;buffer of size
                                                        ;<number>, assigning
                                                        ;the aligned starting
                                                        ;address to <label>

        PAGE <number>, <number>, <number>, <number>     ;ignored

        INCLUDE <file>                                  ;file inclusion

        END                                             ;end

In addition, a "PSECT" pseudo-op was implemented.  It allows program sections
to be defined and bopped in and out of, each with its own location counter and
space.  The Motorola assembler probably does not have this pseudo-op, but no
doubt supports the concept in some way.

        PSECT <name> <space:><begin_addr>:<end_addr>    ;define

        PSECT <name>                                    ;switch to psect <name>


FUTURE DIRECTION

The assembler probably generates bogus code here and there, and no doubt
does not handle all of the syntax.  I welcome all comments, fixes and 
enhancements.

TO MAKE AND USE

Type "make".

The resulting program, a56, is used as follows:

        a56 [-b] [-l] [-o output-file] file [...]

An assembler listing is sent to the standard-output and an ascii-formatted
object file (a56.out) is produced.  The "-b" option adds binary to the listing.
"-l" causes included files to be listed.  "-o" directs the output to the
specified file rather than the default, a56.out.

A separate program, toomf, converts a56.out into "OMF" format suitable for 
downloading to the 56001 via the sloader.a56 program.

        toomf < a56.out > file.omf

AUTHOR

11/28/91
v1.1 8/6/92
v1.2 5/2/94

Quinn C. Jensen
1374 N 40 E
Orem, UT  84057

home: jensenq@zdomain.com (preferred address for a56 correspondence)
work: jensenq@novell.com
