GWASL

                      An assembler program by George Gwilt


The programs supplied are:-

          1. GWASL_BIN - the assembler itself
          2. SYM_BIN   - a program for deciphering _SYM files (see below)

Start the program by EXEC (or EXEC_W) FLP1_GWASL_BIN.

The program multitasks and runs happily with others (I hope), and the screen can
be refreshed by pressing F4 (if the cursor is available).

You are invited to press 1 to start assembling or 2 to quit. Pressing 2 simply
causes the program to disappear. Pressing 1 brings a request for the name of the
file to be assembled. Asking for a null file causes the original menu to
reappear. Assembly results in three files being produced:-

          dev$&name$&'_BIN'
          dev$&name$&'_LST'
          dev$&name$&'_SYM'

where 'dev$' is the device in the name supplied and 'name$' is the remainder of
the name supplied with '_ASM' stripped out if it exists.

During assembly two messages appear 'PASS 1' and 'PASS 2'. When the assembly is
complete the original menu appears.

DESCRIPTION OF THE FILES

1. _BIN
The _BIN file is an executable program file of type 1.

2. _LST
The _LST file is a listing of the file to be assembled preceded on each line by
the PC (program counter) measured from the start then the assembled instructions
in hex and finally the line number. All this will be interspersed by ERROR
messages (if any).

3. _SYM
The _SYM file is a copy of the labels, their values and type. This is given in
the internal form used in the program and has to be processed before it can be
read. This can be done by running SYM_BIN. (Start by EXEC FLP1_SYM_BIN.)

FILE FORMAT

The format of a file to be assembled must conform to certain rules given here.

The general format of a line is:-
          Label Command Comment

Any of these three may be absent. A Label must start with a letter A - Z or a -
z. If there is no Label the line must start with white space otherwise the whole
line is treated as a Comment. Between Labels, Commands and Comments there must
be white space.

White space is defined as a non zero set of characters each of which must be
either SPACE or TAB.

A Command is made up of an Instruction usually followed by Parameters. Between
the Instruction and Parameters there must be white space.

Examples of this are given here:-

   "; TEST_ASM
    ; a program to test something
    ; 10th May 1994
    ;
                    BRA.S     START
                    DS.L      1
                    DC.W      $4AFB
                    DC.W      4
                    DC.B      "TEST"
    ;
    START LEA       CON,A1"

INSTRUCTION SET

The Instructions used are all the 68008 ones with the usual mnemonics as in eg
Andrew Pennel's book Assembly Language Programming on the Sinclair QL. In
addition there are a few organisational Instructions defined below.

DC.<size>   <number>{,<number>}
 <size> = one of B, W or L
 <number> can be decimal eg 496
                 hex     eg $FF
                 string  eg 'This'or "That"

 DC defines one or more constants of the size specified.

DS.<size>   <number>
 This sets a space equal to the 'number' of bytes, words or long words.

EQU         <value>
 The Label preceding EQU is set equal to <value>.
<Value> can be another Label, a number or an arithmetical combination of
these ( + and - only).

IN         <filename>
 This includes the file <filename> as if it were part of the file being
assembled. IN's can be nested.

LIB        <filename>
 This copies the (binary) file <filename> to the _BIN file.

MACRO
 The label preceding MACRO is taken as the name of a macro consisting of all the
instructions between MACRO and ENDM. Later use of 'label' as if it were an
Instruction causes the instructions in the macro to be assembled at that point.

A macro can have parameters signalled in the macro by '\n' where n is the nth
parameter and defined at each macro call by a set of items separated by commas
and following the 'label'.

Any labels used inside the macro, eg for branches, must be followed immediately
by '\@'.

An example may make this clearer.

    "QL_TRAP        MACRO
                    MOVEQ     #\1,D0
                    TRAP      #\2
                    ENDM

     PRINT          MACRO
                    MOVEA.L   \1,A0       CHANNEL ID
                    MOVEQ     #-1,D3      TIMEOUT
     MOVE.W         (\2)+,D2
                    BEQ.S     LP\@        do nothing if string null
                    QL_TRAP   IO_SSTRG,3  parameter string of two items
     LP\@
                    ENDM"

These macros can be used by

          "PRINT    CH_ID,A1"

to print the string at A1 if it is not null.

DATA      <number>
 This sets the data space to <number>. The default is 4000

PCK       <number>
This sets the number of characters of PC printed at the start of each line of
_LST to between 0 and 8. The default is 4.

GENERAL POINTS

1. Programs for the QL will often use calls to the operating system QDOS. To
make life easier an extensive set of constants is predefined (in
GWASS_EQU2_SYM) and automatically loaded by GWASL_BIN. These constants are
listed in the file called GWASS_LIST and contain such constants as "IO_SSTRG".

It is assumed by default that the EQU file is held on FLP1. However this can be
altered by 'config'. In particular a file containing nothing but LF (CHR$(10))
can be used to prevent any EQUates being loaded.

2. Some assemblers allow

          MOVE.L    D0,A1

but GWASL requires

          MOVEA.L   D0,A1

3. If something fatal occurs such as an 'out of memory' condition GWASL prints a
message and then commits suicide.

4. The maximum number of lines allowed in a program and the maximum number of
labels in a program can both be set by using Config.



24th September 2008