                TEST PACK SOFWARE - IMPORTANT
                ==== ==== =======   =========

I know what a Bastard it can be trying to maintain someone elses software so
the following notes are aimed to help anyone lumbered with the task of
maintaining this Arnold 5 test pack software.

There are all sorts of clever tricks one can use to make Z80 software "tight"
( like dudicious use of the wonderful EX (SP),HL ) but I have written the
code to be as simple to read as possible without worrying about size or speed.
I'd suggest from experience that anyone reading this sticks to the same
principles !

FILES & BATCH FILES
===== = ===== =====

All the .ASM files are held in the Z80\ASM directory. They should be the only
ones that need to change. The various batch files available to build the s/w
are:
        \Z80.BAT        ;this .BAT sets the right environment and loads my
                        ; \Z80\STOPZ80 TSR which sits in memory and halts when
                        ; either AVMAC reports an error or AVLNK reports a
                        ; WARNING.

        ASM %1          ;followed by the name of a single module to be assembled

        ASMALL          ;runs through all module names and assembles each. If
                        ; any .ASM files are added or removed then ASMALL.BAT in
                        ; \Z80 should be edited to reflect this.

        LNK             ;Links all the Z80\OBJ files to build the
                        ; \Z80\HEX\TESTPACK.HEX final objet file to download to
                        ; the ICE or EPROM programmer. The files linked are
                        ; those listed in \Z80\LINKLIST. The file should be
                        ; amended if any .OBJs are added or removed.

        XREF            ;Uses the \Z80\XREF files and TESTPACK.SYM to build a
                        ; very useful cross reference file in
                        ; \Z80\HEX\TESTPACK.RPT. This use the file \Z80\XREFLIST
                        ; which should be amended if changes are made.

        LNX             ;This just calls LNK then XREF.

        BUILDALL        ;This calls ASMALL then LNX to assemble, link and
                        ; cross reference all files.


REGISTER USAGE THROUGHOUT TEST PACK SOFWARE
======== ===== ========== ==== ==== =======

Throughout the test software the use of the Z80 registers will be as
follows:

AF    General, never preserved
BC
DE    Used for row/column parameters to routines
HL
IX
IY
SP    Before RAM verified used in fixed return "calls", after = ?RAMStack
I     Used for IM2 tests - set to base table address
R     Never used
AF'
BC'   B'=7F and C'=current 100XXXX value for ULA mode + ROM setting
DE'   Used as row/column to print next character
HL'   bits in BC' used to hold flag info that can't be RAM based


LABELS
======

Throughout the software labels are chosen to be indicative of their role in
life. MultiWord labels are used with each "word" starting with a capital
letter. (e.g. TheBuckkStopsHere). There are three types of label:

 Static variables (probably defined in MESSAGES.ASM) start with a full-stop
  (e.g. .MainMenuTable).

 Dynamic variables (RAM based) are declared in TESTVARS.ASM and have labels
  starting with a question mark (e.g. ?RAMStack). They will actually be
  located in memory at 8000h and are not initialised.

 Code labels are all other labels. In each module it is normal for the first
  "word" of a label to be a derivative of the module name (e.g. in
  ALLTESTS.ASM all labels start "All"). Local symbols all start with "_".


CROSS REFERENCING
===== ===========

All labels are cross referenced by their PUBLIC and EXTERN declarations (see
the Z80\HEX\TESTPACK.RPT file for detailed cross referencing). A typical
example might be:

 MESSAGES.ASM
        PUBLIC  .MainMenuTable          ;accessed in TESTPACK.ASM

 TESTPACK.ASM
        EXTERN  .MainMenuTable          ;declared in MESSAGES.ASM
        :        :       :
        ld      hl,.MainMenuTable       ;(in MESSAGES)


DEVELEOPERS
===========

This note added in 1993 because this set of source files is about the
only remaining documentation I have about the old Arnold stuff.

You will see by example in these files that all the new efatures are
exercised. The one very important thing to note is that there is a
"key" I/O sequence that must be sent before the new features are
accessible. The routines to do this are called UnlockArn5 and
RelockArn5 in the SUPPORT file.

Once that sequence has been sent the routine also switches all the I/O
registers for the new features so that they appear as RAM locations
between 4000h and 7FFFh.

Hope this makes sense!

Cliff Lawson
Amstrad
