Massage (previously known as SMS) V0.61 Source Code
---------------------------------------------------


TERMS OF USE
------------

* This source code is the intellectual property of James McKay in 1996.

* Sections of the code may be used for reference or in part for other
projects (but not SMS/GG emulators!), if you intend to re-use some of this
code for your own project then please give credit in your documentation, if
the project is for commercial sale (unlikely) then some sort of agreement
will have to be attained with the author.  In either case try and contact me.

* The LL_COMM library is the property of its own author and re-use of it will
involve adhering to the terms listed in its own documentation.
Unfortunately, it seems I have deleted the zip and can't find his
documentation!


PROGRAMMING NOTES
-----------------
The Z80A engine is the same as the one in X128 V0.5, but modified to allow
conditions in the 'peek'ing, the same Z80A engine will appear in X128 V0.6
if I ever get round to releasing it.  It still emulates bit 5 and 3 of the
flags.

Part of the emulation is just read in from tables, these are stored in the
file z80.tbl and are necessary for the emulation, so it is important to keep
the function 'open_z80table' to read it in.

To leave the main Z80 loop, you must set the (unsigned char) variable 'quit'
to a non-zero value, this value of quit will then be checked by a case
statement.  The values of 'quit' are #defined in sms_end.c and are used
throughout the entire program.  The values of 'quit' are usually set from
the keyboard interrupt routine.

To make a menu you must set up an appropriate 'quit' situation, then in your
routine you must start with:

scr_copy();
release_keyboard();

which makes a copy of the sms screen and restores the keyboard interrupt to
the usual DOS one (keyboard int not applicable to Unix).  Also scr_copy
changes the palette and stuff and puts it into sms mode, for the larger
screen.

And end with:

init_keyboard();
scr_restore();

However, this system was not very well designed, so you must make sure that
for every one of these 'starts' there must be an 'end', don't do a scr_copy
twice for example, and the keyboard will probably lock up if you try to do
release_keyboard twice.  With careful thought you could have a little blue
debug window running underneath the GG screen.  While in the routine keys
can be read via fsl_asciiext_key and fsl_extend_key, of which #defs for
keypresses appear in sms_t.c.

Warning: there will still be some redundant variables in the code that were
used from X128 and haven't been removed.  Also the code definitions in
sms_def.c are pretty hard to read due to a load of conflicting #defs.
Also the original X128 was designed to be compiled under Borland or Watcom C,
so there are a number of #ifdefs that may need changing, should you be
trying to use the code on a different compiler.

The link up code using the LL_COMM library, hardly works at all!


FACTS AND FIGURES
-----------------

* The Z80A engine emulates the R-register, bit 3 and 5 of the flag register,
counts t_states to determine 'line events' and vertical blank and quite a few
of the undocumented instructions (all the ones that are popular).
Unfortunately it achieves full speed on a 486DX (without any other
processing such as the screen).

* The paging system (using pointers) allows any size pages, as well as
'mirroring' easily, plus the 'DUMMY_MEM' pointer allows write-protect without
'if' statements, which would be really beneficial in a system that had
complex banks of rom and ram.

* Currently set up as 311 lines, 228 t_states per line, as that was the way
it was done on a 'PAL' Spectrum.

* Z80A engine has been compiled under gcc, Watcom (both 32-bit mem model) and
Borland (16-bit, but with the file selectors and so on it became too big).

* 'Endian' can be changed by either removing or keeping in #define LSB_FIRST
in sms_end.c.  (But check the suspicious 'rtemp' variable in the screen
drivers for sms and gg).

* The Massage project ran at a loss of 80!
