OS/2 Shareware BBS: 8 Other/08-Other.zip/x128v05.zip/x128.txt

Text File | 1996-07-01 | 44KB | 1,147 lines

X128 Spectrum 128 Emulator V0.5.

X128 is a Spectrum 128 Emulator for a Unix based machine running X-Windows,
it supports 8-bit (256 colour) and monochrome screens.
X128 for DOS is the MS-DOS version for the PC, a 486DX+ is recommended.

NOTE : THIS VERSION DOES NOT COMPILE CORRECTLY UNDER BORLAND C!!!!!!
It does compile but produces a faulty executable (under BC V3.1 anyway).


FIRSTLY:
--------
Firstly I know little about Unix.

The Unix version is supplied with a Makefile.
It is recommended that these #defines are done through the Makefile, which
has them in a nice easy way to fiddle.


However there are a number of #define s that you may have to change...
These are located at the top of the file x128_t.c except for LSB_FIRST.

#define LSB_FIRST

NOTE : Place this at the top of x128_end.c
If your machine has LSB first memory then define this, if you don't know
then you could just try compiling it both ways!
NOTE : Intel processor = LSB.

#define MITSHM

This applies to the X-Windows version only.
No need to change, it will autodetect, but if the autodetect is substandard,
then you can switch off mitshm completely (causing even slower running).

#define Verbose 1

This applies to the X-Windows version only.
Set this to 0 if you want rid of the startup messages.

#define SCALE2

This applies to the X-Windows version only, don't even think about trying
it on the DOS version.
What this does is double the X and Y dimensions of the window from 320x192
to 640x384, this will inevitably run slower, so use this if you have a
really hot machine!

#define LINUX

This is a type of Unix for the PC, and this allows some of the things that
the DOS version has to be used, namely the PC internal speaker for the
Spectrum internal speaker, and Adlib for the AY-3-8912.
This is done using I/O, not through any C library, so if you are not running
a PC based Unix then DON'T USE THIS OPTION!!  The routines write to ports
0x61, 0x388 and 0x389, these could be anything at all on other types of
machines and could really mash things up, so don't do it.

If you are running another type of PC Unix, then it won't work, so don't do
it.

The Adlib routine has not been tested very much, it is possible that you may
have to be 'root' to get the sound to work but I don't know.

These routines were tested on the Slakware Linux V1.1.18 release.
Sometimes the sound will not start, I don't know why, but when you go back
to DOS you find that nothing else will make noise either!  In my case with
a Sound Galaxy NX Pro card, I have to run \sgnxpro\utility\sg2 (and test the
FM output) from DOS then run (of all things) Z80 before I can be sure that I
can go into Linux and get Adlib output to work.
This maybe due to either old version of Linux, SG card has slight differences
to normal SB or maybe Linux just doesn't like you inning and outting.
It is notable that whenever the startup of Linux says 'OPL2' then the sound
works, and if it says 'OPL3' then it won't.


#define OVERSCAN

All previous versions of x128 have had overscan as the default, Without
overscan a 50Hz timer interrupt is used rather than t-state counting to
determine screen update and interrupts, this leads to worse compatibility,
no ability to deal with fancy screen effects, and flickery bits in some
games.  But AY music sounds are played at a constant speed.  I don't really
like this option, it is a bit of a backward step, which doesn't have any real
benefits.  I didn't have time to remove it, as I was sticking to a deadline,
and it doesn't work under Unix, so don't do it!  The DOS version comes with
the usual x128 (with overscan) and the cornily titled x128lite (no overscan).


LEAVE THE OTHER #defines ALONE!


COMPILATION - UNIX:
-------------------
The Unix version now comes with a Makefile.

To compile, just type 'make'.

If you are short of memory try removing the -O3 option from the Makefile.

The -l... options are libraries, you should have the X11 and Xext libraries
around somewhere, otherwise you can't compile this.
If you have some funny X11 libraries then put them in instead, the
-I option should point to where you have your include files.

If you want to have the double sized window, then I recommend you add the
#define via the Makefile, so that the line in the Makefile looks like
this:

CFLAGS=...... -O3 -DSCALE2

The same goes for the Linux option:

CFLAGS=...... -O3 -DLINUX

And you can do more than one:

CFLAGS=...... -O3 -DLSB_FIRST -DLINUX -DSCALE2

Using gcc is recommended, I have tried CC under Linux and it worked, but I
cannot guarantee it on other machines which do not have gcc.


COMPILATION - DOS:
------------------
A Watcom C compiled EXE is supplied, so you don't have to compile it.

This has been designed to be compilable(?) on Borland C and Watcom C, it
has been tested on Borland C V3.1 and Watcom C (I can't remember what
version).  Note that by using Watcom C it uses the 32-bit memory model,
which seems to result in a much faster EXE (or maybe it just optimises
better).  Do not worry about this if you own a DX2-66 or above, because you
won't notice the difference - it will still run at full speed.  In fact, on
a 486SX-25 Borland does it too slow and Watcom does it a bit too slow.  It
is possible that it will be acceptable on a 486SX-33 but I haven't been able
to find a machine that is faster than SX-25 and slower than DX2-66.
Note that the quality of video card will make a large difference to the
execution speed, eg Trident = Slow.  Anything seems to be faster than this.

Anyway!

If using Watcom:

Rename makefile.wc into makefile, then do 'wmake'.  It should compile
happily.  This is the recommended compiler.
Note : If (when recompiling) the PC locks up, then reset the PC, delete all
.PCH files then 'wmake' again, it should now work.

If using Borland:

Rename makefile.bc into makefile, then change the library path and include
file path in the makefile to that of your Borland C setup, then type 'make'
and it should go fine, providing that you have supplied the correct paths.

If using other:

If you are using Turbo C, then try putting #define __BORLANDC__ at the start
of x128_t.c and hope for the best.
If you are using Visual C, then you will probably have to fiddle with the
code a bit, which will require some knowledge of Visual C - only x128_t.c
should require alterations (unless outp() in AY8910.C is not allowed).  Or
unless you need to change the memory allocation near the bottom of
s128_def.c (grab_mem and free_mem).  The file selector code may need
modification also.
Also consider that a word must be 16 bits wide, this is declared in
x128_end.c , but different compilers can interpret 'unsigned int' as either
16 bits or 32 bits.  If your int is 32 bits then you will have to use
'unsigned short'.  Watcom and gcc use 'short', whereas Borland uses 'int'.
You can also only use a version of Visual C that can produce DOS EXE files,
unless you are planning on a major alteration!  If you get this to work in
Visual C then tell me about the changes.


EASY GUIDE TO SPECTRUM FILES YOU CAN USE
----------------------------------------
file.z80 : Use F5 to load.
file.sna : Use F5 to load.
file.slt : Use F5 to load.
file.voc : Use F7 to select, then type load "" or use tape loader.
file.tap : Use F7 to select, then type load "" or use tape loader.

If you get a .z80 file with other files called .dat then these will be
dealt with automatically, just load the .z80 as described above, and if the
filenames of the .dat files are wrong then the file selector will appear and
you will have to select the correct DAT, or press ESCAPE.  If you downloaded
it then this should not be the case.  If the file is a SLT format file
(which has still been named .z80 at the end) then this emulator deals
with it automatically.

file.dsk : This cannot deal with +3/CPC disk files.
file.mdr : This cannot deal with microdrive cartridges.

Any other file type you come across cannot be handled in this version of
the emulator.


TROUBLESHOOTING - UNIX:
-----------------------
SYMPTOM : Compile failed with 'out of memory' style error.
CAUSE   : Try removing the -O3 option and try -O2 then -O1 all the way down
to -O0, this will result in faster compilation, but will cause a slower
emulation.  Each one is progressively slower.  Or, if you are the head
cheese of the system, then setup a bigger swapfile.


SYMPTOM : Compile failed with a 'couldn't find' type of error.
CAUSE   : Probably the X11 and Xext libraries.  If you don't have them then
I don't know how I can help you.  If you have them somewhere else, then you
could try messing about with the -I option to direct the compiler to the
right place.  Or -l.


SYMPTOM : The screen is all full of mush.  And no BASIC or any snap will
work, but you can load stuff in using the F-keys.
CAUSE   : Your machine could be the opposite endian compared to how this
was compiled, try using #define LSB_FIRST or if it is defined then delete it
and compile again.
CAUSE   : Your display is not 8 bits per pixel (256 colour) or 1 bit per
pixel (monochrome).  These are the only screen modes I have written drivers
for, all you can do is see if you can alter the screen mode on your terminal
to one of these values.


SYMPTOM : On a colour screen, the colours are wrong, or are missing.
CAUSE   : There is a limited number of colours allowed on screen, you may be
running another application that is reserving the palette for itself, so
you could try quitting x128 then closing all the other applications then
try running x128 again and see if it works.
CAUSE   : I did see a message somewhere from someone who said they had a
16 colour screen (4 bits per pixel), if you do then it won't work anyway
as I have not written a 16 colour screen driver, and if I had it would be
unlikely that I could snatch every palette colour available.


SYMPTOM : The emulation is too slow.
CAUSE   : Try removing other background processes that could be taking up
CPU time, also try running x128 on a mono terminal as there is less graphic
data to move about.  If you compiled without the -O3 option then re-compile
using this - if your machine allows it.  If you are running on a terminal
that does not use MIT shared memory then try and find one that does.
Alternatively all you can do is get a faster machine or hope that a future
release of this is more efficient.  Or you could try using the frame skip
menu option to cause less screen output.


SYMPTOM : The emulation is too fast.
CAUSE   : You are obviously using a hot Unix workstation, so what you can
do is select the menu option 'Alter Slow Down' which is a value between
0 and 65535.  The higher the number the greater the delay, 0 is no delay
and 65535 is a lot!  Don't set it to a ridiculously high value, or you'll
get stuck.


SYMPTOM : The window opens up but then closes and some sort of error message
appears.
CAUSE   : Possibly the wrong LSB/MSB setup (see above).  Or it could be that
you are running on the wrong type of screen, see if there is anyway of
altering the screen mode of the terminal to 256 colour or monochrome modes.


SYMPTOM : I exited the emulator, and now the key autorepeat is turned off!
CAUSE   : The emulator turns off the autorepeat for its emulation, if you
kill the window by clicking on the top left of the window and shutting the
process down then the exit routine will never be reached and autorepeat
will remain off (unless you kill the window while the fileselector is on,
in which case the autorepeat is turned on).  You may be stuck by the number
of function keys on your terminal though, since F10 is quit and I have seen
some Unix machines that have only 8 function keys...  In this case use the
F1 or Help keys, then you can choose any function key option from the
little menu.


SYMPTOM : The file selector will not open.
CAUSE   : Desperate shortage of memory!  Close some other windows.  There
is a line in x128_t.c which says:
#define FSL_BUFF UNIT_SIZE*2048
The 2048 is the number of files in a directory, so you could change this to
something less and recompile.


SYMPTOM : Some of the function keys don't work.
CAUSE   : Some X-windows managers like to steal the function keys for its
own purposes.  As long as F1 or Help work, then you can pick any option.
CAUSE   : Unix terminals tend to have different numbers of function keys
on their keyboard.  Use F1 (or Help key) to select any of the options.


SYMPTOM : Linux is returning no sound.
CAUSE   : You did not compile with -DLINUX in the Makefile, or you did but
the compiler used the old object files, so make sure that -DLINUX is in the
Makefile and delete the *.o files.
CAUSE   : You do not have an adlib card.
CAUSE   : You do not have permission to access the I/O ports, so try this
as root instead.  (Unless someone else is root!)
CAUSE   : The sound is toggled off, press F11 or select the option from
the help menu (F1).
CAUSE   : Sometimes the Adlib card likes to produce no sound when you get to
Linux, try running an Adlib test program before x128 to try and reset the
soundcard into working order again, even if this means using a DOS program
then going into Linux.


TROUBLESHOOTING - DOS:
----------------------
SYMPTOM : The emulation is too slow.
CAUSE   : Try running this in DOS, if you are using a Windowed environment,
If you compiled this then try re-compiling with more optimisations (varies
depending on compiler).
Alternatively all you can do is get a faster machine or hope that a future
release of this is more efficient.  Or use the frame skip option, see near
the top of this document on how use this option.  Another option is to get
your hands on a much faster video card.


SYMPTOM : The emulation is too fast.
CAUSE   : You must be using a Pentium or DX4 processor, or you have a very
fast video card.  What you can do is select the menu option 'Alter Slow
Down' which is a value between 0 and 65535.  The higher the number the
greater the delay, 0 is no delay and 65535 is a lot!


SYMPTOM : The EXE supplied will not run.
CAUSE   : Make sure you are using a 386 or above, if you compiled with a
16-bit memory model then make sure you have about 500K base memory or more.
CAUSE   : DOS4GW returns an error.
Oh dear.  Try the following things:

set DOS16M=+  (this tries to fix problems with funny memory).

or, for example:

SET DOS16M=@2M-4M  (this will force DOS4GW to use the memory 2Mb to 4Mb)

Otherwise try and get a 16-bit compiled EXE.


SYMPTOM : The Borland C makefile will not compile the emulator.
CAUSE   : Make sure that the library path and include file path in the
makefile have been set correctly, as in the Borland C IDE (Alt-O then D).
CASUE   : Since V0.4 I have not managed to get it to work either!


SYMPTOM : The file selector will not open.
CAUSE   : Desperate shortage of memory!  Free up some memory before running.


INSTRUCTIONS:
-------------
Once you have typed 'x128' to run the emulator and the 128 BASIC screen
has appeared (hey, monochrome users can't see the menu bar!) then the
following function keys are available:


F1 - HELP
---------
This brings up a list of the functions keys available, on the Spectrum
window, press ESCAPE to go back to the emulation.  This can also be brought
up by the 'help' key on some Unix keyboards.
Now when you bring up this option, you can select the function of any
other function key from the menu that appears, by using cursor up/down and
return to select.  The selected option will have a > beside it.  When you
have completed the selected option, you will return to the emulator, not
the help screen.

Options available here that aren't available anywhere else are:


Alter ULA Delay:

This controls the lining up of overscan bits (see F8 and F9 keys), the
max. value is 255.


Alter Frame Skip:

This allows you to set up the screen update, 1/1 is full update, 1/255
updates the screen once every 255 times.  1/0 is effectively 1/256.
Note that most other emulators have 1/2 as the default whereas x128
usually starts as 1/1 screen update.


Alter Slow Down:

I've got a for loop in the code that is executed every Z80 instruction,
this causes a slowdown for the benefit of fast machines, the upper bound
is determined by this value (which can be between 0-65535).  0 is no
delay, indeed the for loop is not even executed.  65535 is a huge delay,
where you can see the display build up a line at a time (but on Unix
you'll just get stuck if you set it too high).


The values can be changed by moving the cursor to the option and pressing
left (-1), right (+1), page up (-10) or page down (+10).
Remember that Page up/Page Down is -/+ on the keypad for some Unix
machines.
The values will wrap round if you try to pass 0 or its maximum value.
These options don't return to the emulator when you select them, you have
to press Escape.


Keyboard Issue:

Press return to toggle between issue 2 and issue 3, where issue 3 is by
far the most common.  Occasionally a program will need this option to be
set to 2 (usually an old program) otherwise the keys won't respond.
A .Z80/.SLT file will change this value when you load it.
Note that all 128K Spectrums were issue 3 and some Spectrum 48K were
issue 2, but not that many.


Note that options like load snap, save z80, joystick select, memory mode,
etc return to the help menu, so that you can load in a snap and resave it
with changed settings.


F2 - NMI (M128)
---------------
Yes, the Multiface 128 by Romantic Robot, all you need is the ROM!  It has
to be called mf128.rom and be 8192 bytes long.  Without it, this will crash
the Spectrum when you press F2.  This ROM is such a hot ware, that I am
risking my life just by talking about it!  If you can get the Genie 128
software then you have a push button disassembler on your hands.

Note that pressing the button more than once causes a crash, just like the
real thing!


F3 - RESET/MEMORY MODE
----------------------
From here you have a little menu that you can select reset to 48 or 128
mode, or you can try to swap modes with no reset, note that from 128 to 48
no reset mode that ram page 0 will be slotted in regardless of what ram
was actually paged in.
You can use cursor up/down to move, return to select and escape to abort
selection.

You are on your own trying to work out the keywords in 48K Basic.


F4 - JOYSTICK SELECT
--------------------
This will map one of 4 joystick possibilities (Kempston, Sinc 1, Sinc 2 and
Cursor onto the cursor keys and TAB for fire.

You will see the 4 options and a > which points to the current option.  To
select one use cursor keys up and down then press return to select.  To
abort and use current option, press ESCAPE.

You can press left or right to toggle caps on/off for cursor keys.

Note that .Z80 files set the joystick configuration when loaded.
Whether cursor has caps shift included is not stored in a .Z80 and you
may have to change this yourself.


F5 - LOAD SNAP FILE
-------------------
Yes, this will allow you to load, at any time, a V1, V2 or V3 .z80 file in
48K or 128K mode (it will automatically pick the correct mode for the snap).
This also allows loading of .sna files and .slt files.

These files are exactly the same format as those used by the famous Z80
Spectrum emulator for the PC.  Note that any hardware like Interface 1,
SamRam or MGT will be stripped off and ignored, if that piece of hardware
was paged in at the time the Z80 was saved, then it might not work.
But this is not usually the case.


F6 - SAVE Z80 V2/SLT FILE
-------------------------
This allows you to save the whole of memory to a snapshot file.  It can
save in 48K or 128K mode and will decide by itself what memory it has to
save.  The resulting file can be loaded back in using F5, or can be loaded
in by another emulator that supports Z80 V2 files.
This option is good for cheating at games.

A little window will pop up containing the full path of the last Z80 file
loaded, you can type the name you want, and you can use backspace or delete
to ... delete a character, you can choose the directory to save to by
altering the path.  If you decide that you didn't want to save after all
then press ESCAPE.  The code will try to be clever and determine whether you
have typed .z80 at the end of the line, and append it as necessary, but you
could still confuse it by calling a filename a.a or whatever.
If the file you are trying to save already exists then you will be given
the message 'Overwrite(Y/N)?'.  You can reply 'y' to overwrite, 'n' to abort
and ESCAPE to abort also.
If you are saving a .SLT file, then the level data will be appended to the
newly saved file (which will have .SLT as its extension), however try to
make sure that you have space on your drive otherwise it is possible you
could create difficulties.  Let me elaborate:

If there is no permission to create the temporary file (dump.tmp), then
the save will be aborted with no difficulty.

If there is no permission to create the final completed file, then you
will be left with 2 separate files which you will have to merge from the
command line.  (If you were trying to overwrite then you have probably
lost data.)

So you would have to exit the emulator, then (after clearing space),
you will have to do:

DOS:
copy /b file.z80 dump.tmp new.slt

Unix:
cat file.z80 dump.tmp >new.slt

(I think).

Note that dump.tmp will always be saved in the directory you were in when
you started the emulator, so make sure you have write permission to that
directory!


F7 - SELECT TAP/VOC FILE
------------------------
You want multiload games on emulator, yes?  Well, this allows it to happen
by being a file containing a string of just the important data from saves.

These TAP files are the Z80 compatible files, NOT the Warajevo emulator
ones, they won't work at all.

Firstly select the file from the file selector.

To load a file you must either:

Use the 128 BASIC Tape Loader (just press return).
In 128 BASIC (type load Meta-P Meta-P Return).
In 48 BASIC (type J Meta-P Meta-P Return).

(Meta is the diamond shape, you can also use ALT).
(On the DOS version use CTRL).
(You can now use SHIFT-' for ")

Note for monochrome users: when you start up the invisible bar is on the
Tape Loader option.

A VOC file is a Creative Voice Sample File, ie a multimegabyte-sized sample
of your Spectrum cassette, you will have to make this on your own using
some sampler and whatever.

The VOC file emulation is pathetic, some games that work on Z80 will not
work on this, I have no idea why, when you are making the VOC you need
perfect, and I mean PERFECT conditions.  Good tape, good deck, Azimuth screw
lined up and Volume on SB input set to high.  Out of 5 games I managed to
get 1 to work (SDI, Speedlock 3 or 4).  The same 4 that didn't work, would
not load in Z80 either, but they did get further.  Also there is the problem
of bad sampling software that likes to save bits to disk while it should be
listening to the tape!  Also I have not emulated the 'silence block' that
some samplers will try to save.


F8 - VOC OPTIONS
----------------
'VOC OPTIONS' is not a very catchy name, it is also not a very good use of
an entire F-key, with a couple of fiddly options no-one will ever use.

Threshold : The data in the VOC file is stored as a char with 128 as its
centre, the value 128 is total silence and the rest represent positive
and negative sound values (with 255 and 0 being the loudest), so the
threshold is added to and subtracted from 128 to determine what is silence
and what is noise, after all, a Spectrum tape will not be saved with
CD-quality sound, there will be tiny amounts of fuzz and noise that must be
ignored.  On a really noisy tape you might want to increase the threshold
to ignore more of the noise, on a ridiculously quiet tape you could reduce
the treshold.

No_of_t_vary : More of a debug option for me than a usable option for you,
quite simply, setting this to a value 1-127 is useless.
Setting it to 128-255 (where 255 is -1 and 254 is -2 etc) may do something,
it will load the VOC slightly faster (but not noticeably) and may on some
occasion cause the VOC to work better, the value 230 is the most useful.


SHIFT-F8 - INCREMENT ULA DELAY
------------------------------
T-States are a tricky business.

The Spectrum +2A manual says that there are 228 t-states in a screen line.
Z80 Emulators documentation says 224.
(It turns out that the Spectrum 48K uses 224*312 and the 128K uses 228*311
which is now supported).
Games that you try say 'Any number, all different'.

This adds a value to the number of t-states counted at the end of every
screen line (192 of them).
So you can use this option to help align up that nice overscan bit on the
screen.

This option usually moves overscan bits DOWN the screen.

Now, 4 t-states are added to the counter every time you try to write to
memory between 16384-32767 while the screen is being updated by the ULA,
this lines up the effect in Agent X 2 nicely.  (But you don't have to do
this anymore).
It starts at 0, if you move too far, the emulator performance will start
to be unusual, as this will affect the number of instructions between
interrupts.
The ULA Delay is reset to 0 every time you reset or load a snapshot.


F9 - NO FUNCTION
----------------
Ah!  Future development!  I expect that I will put the advanced SLT options
here, you should have the ability to view the loading screen, instructions,
pokes and scanned JPGs of the cover (no chance).
At the moment it does the same as SHIFT-F9.


SHIFT-F9 - DECREMENT ULA DELAY
------------------------------
See above for information.

This option usually moves overscan bits UP the screen.
Once you reach 0, it will not go into negative numbers.

The ULA Delay is reset to 0 every time you reset or load a snapshot.


F10- QUIT
---------
This will quit the emulator and close the window and all that sort of thing,
and yes it does remember to de-allocate the memory and close the TAP file.
On exit you will be told what ULA Delay you had.


F11- SOUND OPTIONS
------------------
You see three useful options:

Sound is On/Off : Press left/right to toggle this.

Create/Close PSG File : This allows you to log the OUTs to the AY-3-8912
sound chip, you will be asked for a filename, it will automatically have a
.psg extension, the files are then playable using the utility PSGPLAY, which
comes with the Unix version of fMSX (/dev/dsp or /dev/audio), a DOS PSGPLAY
doesn't exist yet (I think).  Note that all interrupt marks are 0xFF and the
multiple marks are not used.

White Noise On/Off : I have added some really pathetic emulation of the white
noise of the AY-3-8912 through the Adlib card, using the snare drum channel,
so I have included this option to turn it off.


MULTIFACE 128
-------------
By pressing F2 the M128 menu will appear, if you have the ROM.

The ROM:

mf128.rom 8192 bytes long, and is a dump of the values of the Spectrum from
0-8191 AFTER the mf128 rom has been paged in.

It is also tightly entombed within the file ROMS.BIN that comes with Z80.

The MF128 pages in 16K, of which 8K is ROM and 8K is RAM:

0-8191     ROM
8192-16383 RAM
16384+     Usual Spectrum memory.

The memory is paged in and out like so:

IN A,(191) Pages MF128 in.  Returns 127 if the normal Spectrum screen is
visible, or returns 255 if using the 128K second screen in RAM 7.
IN A,(63)  Pages MF128 out.

When the MF128 is paged in, OUTs to 32765 still work, so that you can access
all RAM, but for ROM the OUT to 32765 dictates which ROM will be visible
after you page the MF128 back out.

The NMI goes like this:
    iff2=iff1;
    iff1=halt=0;
    push(pc.W);
    pc.W=102;
    in(191); /* This bit for MF128 only */

Also t_state may increase by 11 and the R-reg may go up but this is
uncertain.

The fact that half is ROM and half is RAM presents the problem of having to
write-protect an 8K area, which means you have to rethink your memory
structure and change it to 8K blocks.


USING THE FILE SELECTOR
-----------------------
Use the cursor keys to move up and down, the file selected is the one at
the top (with the inversed colours).

Directories are Magenta and Black with a slash preceeding the name.
File are Blue and White.
Drives (PC) are Cyan and Black.

You can change directory/drive by pressing return while it is being pointed
to, the listing of that directory will then appear for you to view.

Keys:

Up/Down : Move Up 1 file/Down 1 file.
Page Up/Page Down : Move up 22 files/down 22 files.
Home/End : Move to the top/bottom of the list.
Return : select the file/drive/directory.
Escape : leave the file selector without loading anything.

Note that I couldn't get page up/down or home/end to work on the Unix
keyboard, so page up and down is now replaced by - and + on the keypad.
- is page up and + is page down.  Look at the keypad, the + is below the -,
this will soon become instinctive!  Page Up and Page Down do work on
Linux though.

Another feature is the file search by typing letters, so if you press 'b'
the pointer will be moved to the first file (not directory) that starts
with 'b' (case insensitive).  If the search was successful, then when you
type another letter you will be searching for the 2nd character position
and so on, if a search fails, (in which case the pointer will not move) the
next attempted search will begin with the first character again.
If you move the pointer with cursor keys, page keys or home/end then the
next search will be on the first character.  Also included in the term
'letters' are numbers and some punctuation symbols.


COMMAND LINE OPTIONS
--------------------
You can get x128 to do things from the command line by adding the following
parameters:

x128 /?
Shows all the command line options available.

x128 /48
Resets to 48K mode on startup.

x128 /128
Resets to 128K mode on startup (default).

x128 /quiet
This starts up the emulator with the sound off, it can still be switched
back on by F11 or the help option.

x128 /delay <number>
This sets the slow down delay (0-65535), eg x128 /delay 30000

x128 /frame <number>
This sets the frame skip value (0-255), eg x128 /frame 4

x128 /ula <number>
This sets the ULA delay (0-255), eg x128 /ula 30

NOTE: With all these numerical options, entering non numbers, or numbers
that are too large will cause confusion.  Generally it will decide that
the value should be set to 0, but in the case of /frame this is
effectively 1/256 so you will get a big delay before the screen updates,
so don't enter bad numbers!

x128 <filename>
If the filename is a sna or z80 then it will automatically load (and /48
and /128 will be overridden by the type of snap loaded).  This will work
for slt files as well.
If the filename is a tap then it will be selected, but you will still have
to load it via the tape loader or by typing load "".
I suppose this means that x128 can now be used in this 'play spectrum games
across the web thingy'.


SLT FILES & UTILITIES
---------------------
The .SLT file is a new file format, it is best described as 'exactly the
same as the DAT file idea, but all in the one file for ease and space
saving'.

Two utilities are supplied DAT2SLT and SLT2DAT.

DAT2SLT, use this to squash all the files of a Z80 and DATs into a single
SLT file (you must use a V2 or V3 .Z80 as the main part of the file, if
the main file is a .SNA or a V1 .Z80 then convert it to a V2 .Z80 by using
the help menu load and save options within the emulator.)

Usage:

dat2slt robo robot

This will squash robo.z80 and robo*.dat into the file robot.slt .

dat2slt roborobo roborobo /dos

This will squash the roborobo.z80 and roborobo*.dat into the file
robo.slt , but the filenames of the .dat files that are searched for will
be in the DOS format, ie only 8 letters, for example, under Unix if you
are looking for level 1 of roborobo, then the name of the DAT is:

roborobo1.dat

but for DOS it is:

roborob1.dat

So use /dos if you are dealing with DOS style DATs under Unix, of course
you do not have to do this if you are running it on a PC.


SLT2DAT, use this to undo all the files.

Usage:

slt2dat robo bog

This turns robo.slt into bog.z80 and bog*.dat , you can use /dos if you
wish (default for PC version) this can also be used as an easy way to
rename a set of DATs.


When overwriting a .slt file within the emulator (for example, you are
regularly saving your progress through a game) the emulator will try to
append all the level data of the old .slt onto the new one.  Exactly
what will happen if the space on your drive is too low is best described
as 'undefined'.  The emulator will spawn the dat2slt and slt2dat
utilities so make sure they are in the same directory as the emulator.
This will mean that a large number of files will be around during the
saving, basically you will require approximately 2 or 3 times the size of
the original SLT file of space on your drive.

The loading screen option now included, means that once the SLT has loaded,
the screen is read from the SLT file and displayed before the SLT starts, you
then press a key to start the SLT, this allows lazy-boys to add loading
screens to bad quality snaps with no programming knowledge required.  All you
have to do is have the 6912 byte long loading screen called <name>.scr in
the directory along with all the other <name> files then run dat2slt as
usual.


GOOD BITS:
----------
Emulation of all known opcodes.

Emulation of undocumented opcodes, even the ones between ED40-ED7F that
are listed in Z80.DOC which never get used.

Runs on 8-bit or mono terminal and autodetects (Arnolds bit).

Autodetect MITSHM (Arnold again).

Careful timing of screen output to allow screen accuracy of 8x1 pixels and
border accuracy of one colour per line.

Ability to line up overscan bits on the screen, as it seems that different
games and different Spectrums had slight speed differences, this is often
as much fun as the game itself.

Some emulation (on DOS) of AY-3-8912 soundchip, this part by Marat
Fayzullin & Alex Krasivsky.  Now with added shoe cleaning noise.

Joysticks (as seen in Z80) are mapped onto the cursor keys.

Load ANY type of Z80 file, and play!

Gauntlet is now playable on a 486SX-25 (with good video card)!

Option (at compile time) to have a double size window in X-Windows, the
window is 640x384 pixels.

ED FB level loader trap supported.  It will try .dat first then .DAT before
saying it can't find it.  Also will try the DOS style then the Unix style
filenames before admitting defeat.

Hot file selector!

Save Z80 V2 snap files in 48 or 128 mode.

SLT format files are supported, load, save and also includes the additional
loading screen as seen in the advanced specification.

Alter keyboard issue, caps (with cursor), ula delay, slow down and frame
update within the emulator dynamically at any time.

VOC file loading.


BAD BITS:
---------
Speed : Not bad at all!  The DOS version still runs faster?  But....
The speed is very up and down, causing irregular AY playing, but this tends
to even out on a faster PC (a bit).

No support for any terminals that use 2, 4, 16, 24 or 32 bits per pixel.

Overscan in some demos, is off line and cannot be fixed with F8 and F9
fiddling (Although the new ULA delay/memory cycle is closer than before).

AY sound is incomplete, and some sounds are now played at a fixed volume due
to the fact that envelopes aren't emulated.

The Overscan Demo.  It times the Spectrum to determine which model it is,
and if it doesn't like the timing it will refuse to put any colour on the
screen!

Look:

33339 ei
33340 halt (interrupt jumps to 32512)
32512 ld (33154),hl (redirects interrupt to jump to 33348)
32515 ei
32516 inc bc
32517 jr 32516 (this is exited by interrupt)
33348 .....

(I=128, points to 33153, all in uncontended memory)
(SP=33280, in uncontended memory)

This is the code used in Overscan Demo, it is entered with bc=0 and the
interrupt routine just a jp 32512, ld (33154),hl sets the
jp to 33348 which is the comparing routine.

Consider that 33345 and 33346 take up 18 t-states, and that there are 70908
t-states in the 128Ks interrupt cycle.  70908/18=3939 so that bc should
equal approximately 3939.

x128 has bc=3937,
A real Spectrum 128 has the value bc=3185 !!!
Z80 V3.02 gives the value bc=2803 (I have no idea where it gets this from).
Z80 V3.03 has the value bc=3212 which is a bit unlucky because it just
falls outside the timing required:

This is the timing desired by the comparing routine:

3115-3131 Spectrum 48K
3177-3193 Spectrum 128K/+2
3608-3624 Spectrum +2A/+3

Note that Z80 V3.03 in 48K mode produces bc=3155, which is unlucky again!

The reason for this is the slowdown caused by the code executing below
32768 (contended memory), as a result - the loop is executed less times
than usual before the interrupt occurs.

When you think about it, if you want to get the emulator to return 3185
as the value then:

(19 = IM 2 setup time, 16 = ld(NN),hl, 4 = ei)

70908 - 19 - 16 - 4 = 70869 (slowdown ignored in this case)

70869/3185 = 22.251 t-states

If you want to assume full slowdown then,

(19 = IM 2 setup time, 28 = ld(NN),hl, 8 = ei)

70908 - 19 - 28 - 8 = 70853 (assume 4 extra t states per mem read)

70853/3185 = 22.245 t-states

In other words, 'inc bc' and 'jr -3' must be set up to take about 22.25
t-states for the Overscan Demo to detect properly.

But, 22 or 23 is not good enough,

(first 70869 t's then 70853 t's)

22.0 would give bc=3221 or bc=3220 (illegal)
23.0 would give bc=3081 or bc=3080 (illegal)
22.1 would give bc=3206 or bc=3206 (illegal)
22.2 would give bc=3192 or bc=3191 (legal)
22.3 would give bc=3177 or bc=3177 (on the limit, probably outside)

So there you go, it is impossible to get the overscan demo to work without
introducing tenths or indeed hundredths of t-states.

And how would the time lag on the loop be split up??
You have 4.25 t-states to split up between three contended memory reads
this doesn't work too well on integer numbers, and the .25 is too important
to cut off.

As a result, overscan demos that have auto-calibration will not work, as
I have given up the mem read delay (unless someone comes up with some good
ideas), the auto-detect routines in these demos use the mem read delay,
but the actual overscan routine will often be more dependent on the mem
write delay (which I have included, as a 4 t-state delay) so things with
non-calibration will look better.

Aquaplane is dependent on both read and write delay, due to the way it has
it's code in contended memory, and as a result is off line.  You will have
to use ULA delay to line it up.
If you want to run the Overscan demo, then set ULA delay to 30, then press
return then break (to get back to 'you have incompatible...') and when you
press return again, you should have a nice mess on the screen, which you
can partially line up with ULA delay, but not perfectly.


FUTURE IMPROVEMENTS:
--------------------
Top and bottom borders, at least 24 pixels worth either side.

Speed : Ever Better.

Shading for the double sized window on mono screens.

Maybe the ability to save taps.

I don't see how I could do sound, surely all machines are so different?
(Well, proper sound).  Ah!  Use a 'dsp'.

Better t-state timing for overscan demos.

Emulator figures out what speed it is going at, and allows you to enter
a percentage rather than a number for the slow down delay.


HOW TO GET GAMES:
-----------------
Check ftp and www sites for files, Norway seems to have a lot.
There are some on ftp://altair.komkon.com (good for USA)
Try ftp://ftp.nvg.unit.no
Most sites will be in Europe.  Try doing a web search for 'Sinclair' or
'Spectrum' if you have plenty of spare time that is.
You could register Z80 and get a tape interface and plusd file copier.


CREDITS:
--------
James McKay : me : Author of the big (getting less) rubbish bit of the code.

e-mail [e-mail]
Until June/July when I will probably become a bin man.

Marat Fayzullin : Wrote the original Unix/X drivers for VGB and fMSX, and
I used these in x128.  Also his source gave the idea about how to access a
variable as bytes and words at the same time.  Also the AY emulation is
written by Alex Krasivsky and him.

http://www.freeflight.com/fms/
ftp://altair.komkon.com
e-mail [e-mail]

Arnold Metselaar : Wrote improved Unix drivers for fMSX, I tore this to
pieces to make the mono screen for x128.

e-mail [e-mail]

ALSO:
-----
Gerton Lunter : His Z80.DOC that came with his emulator, was a very useful
technical reference.  Maybe if I get V3.04 it will be an even better one.
Spectrum +2A Manual by Amstrad.
Master Machine Code On Your Amstrad CPC 464 And 664 by Jeff Naylor and
Diane Rogers.
Understanding Your Spectrum by Dr. Ian Logan.
My Spectrum 128 with it's dodgy keyboard.


HISTORY OF DEVELOPMENT:
-----------------------

V0.0 Date (UK DD/MM/YY) : 02/02/96
V0.1 Date (UK DD/MM/YY) : 08/02/96
V0.2 Date (UK DD/MM/YY) : 26/02/96
V0.3 Date (UK DD/MM/YY) : 19/03/96
V0.4 Date (UK DD/MM/YY) : ??/05/96
V0.5 Date (UK DD/MM/YY) : ??/06/96


V0.4 Bugs Fixed:

* Checksum calculated properly in situations where less bytes are requested
than are available (in a TAP), so Frank Bruno now works.

* You can now save Z80 files!  A bug meant that it tried to save SLT files
all the time.

* Some SLTs would not load (any one with a level 0) this has been fixed.

* Any channel with volume governed by the envelope generator would not play
at all, now it plays at a fixed value.

* Kempston now read from any port that has bit 5 (32) reset, so that Command
Quattro etc works properly, thanks to information from Rui Ribeiro.


V0.5 Improvements:

* New method of write-protecting ROM allows for faster memory writes.

* Now saves PSG files.

* For the second time, I have been unable to find any Z80A bugs.

* SLT file format now includes Loading Screen from Additional Specification.

* DAT2SLT and SLT2DAT now handle a single .SCR file for one part of the
advanced SLT spec.

* Keyboard emulation changed slightly so that caps is not switched off after
using shifted keys like <>?:"_+ these.

* Multiface 128 emulation, if you have the ROM!

* VOC file loading, but not very well.

* White noise through Adlib card, not very good though, so I included the
following option.

* Ability to switch off the poor white noise emulation via a menu.


KNOWN BUGS:
-----------
Konami Ping Pong (released by Imagine) has corrupted bats, this is caused by
this (near the top of x128_def.c):

#define spokeb(oset,bpval) \
    mwtemp=oset>>13; \
    SRAMW[mwtemp][oset&0x1FFF]=bpval; \
    if((CONTENDED[mwtemp]) \
    &&(!(t_state>>7))&&(vline&192)) t_state+=4;
/* The 'if' is Spectrum specific, if you are using this code for
another Z80 thingy, do not include that line.  It is an attempt at
emulating the mem write delay in ULA contended memory */

If you want to play Ping Pong properly you can remove the last two lines of
the #define, this will cause Hostages 128 to crash though....  And Dos users
will be unlikely to get to recompile it.
This problem proves that my t_state timing is running on luck rather than
accuracy.
But look at the line above the two!  See how it causes write protection of
the ROM area without an 'if' to slow down access!


HELP!!!
-------
If anyone can solve the following problems then don't hesitate to contact me
(e-mail address above, but will be out of date):

1.  STAT problem.
After 128 stat's are done on an uncached CD things really slow down a lot,
such that 319 files takes 27 seconds!!!!  This may also happen on other types
of drive, but I don't have a situation where that happens, also this might
only happen on DOS (maybe).  My current solution is to use some Watcom
specific code which speeds it up nicely, but I would prefer a stat fix.

2.  Adlib - Linux problem.
For some reason, the Adlib card likes to produce no noise in Linux unless
you run some DOS noisy things first (see way up for details), yet even when
it is refusing to make noise, the timers work and the card is detected.
Maybe this is a SB Pro mixer chip problem?