FAST Release 1.0
================

CONTENTS
--------

1.	Introduction

2.	Copyright Notes

3.	Description and Usage
3.1	Compiling FAST
3.2	Using FAST
3.3	Command Line Options
3.4	Floppy Disks
3.5	ROMs and ROM troubles
3.6	Compatibility and Emulation Speed
3.7	Keyboard

4.	Future Work

Appendices:
A	I/O and Device Emulation Summary
B	Bugs


1. INTRODUCTION
---------------

Welcome to FAST, the Fine Atari ST emulator.

Q: Is it really fast?
A: On fast computers it is (see 3.6).

Q: What do I need it for?
A: Uh, good question.  I asked myself this question many times during long
   nights of coding and optimizing and experimenting.  If you come up with
   a satisfying answer, do let me know.

Q: Does it work properly?
A: It looks very much as if it indeed does.  Don't expect miracles, though.

Q: What do I need to run FAST?
A: The real thing, to copy the ROMs.  Next, a PC running Linux or a SPARC
   workstation. X11.

Q: Is it all for free?
A: Quite. Read the next section `COPYRIGHT'.


2. COPYRIGHT
------------

FAST may be distributed under the terms of the GNU General Public
License (GPL) version 2 or later.  See the file `COPYING' for details.

The FAST distribution does not include Atari ROM code.

Author's address:
		    Joachim Hnig
		    Spiestrae 16
		    90441 Nrnberg
		    Germany

E-mail:
		    hoenig@informatik.uni-erlangen.de

FTP sites:
		    <unknown>


3. DESCRIPTION AND USAGE
------------------------

3.1 Compiling

FAST has been compiled and tried on a Linux PC (X11R6, 1.2.8 Kernel or later,
gcc 2.6.3) and on a Sun SPARCstation LX (X11R5, SunOS 4.1.3, gcc 2.5.8).

There's a Makefile.  You will probably need to edit paths and flags
according to your needs.  Use of gcc -O2 ist strongly encouraged, as it
REALLY makes a difference.  Use `make i386' on linux machines (`make
sun4' on Sun workstations).

FAST has never been tested with Solaris 2.x.  This version does not support
monochrome (e.g. bwtwo) frame buffers.

3.2 Using FAST

After compiling, you should find a program named st.i386 or st.sun4 in
your directory.  This program expects to find the rom image in a file
named `rom' (see 3.5 ROMs and ROM troubles), the floppy disk images in
files named `diska' and `diskb' (see 3.4 Floppy Disks).  You will find a
default boot disk (diska, drive A) image included in the distribution,
while diskb (drive B) is a symlink to your physical floppy disk device
(/dev/fd0).  After you have provided the rom image you are all set to go.

After invoking st.i386, if your ROMs are OK, FAST will print some status
messages to the terminal screen and open a 640x400 monochrome window
you haven't seen since ages past.

A word on the mouse.  After starting up, you will see two mouse pointers
in the FAST window.  This might be confusing, even more because both
pointers usually get out of sync quite soon.  In order to switch off the
X11 pointer, press the middle mouse button while in the FAST window.  The
mouse will then be attached to the emulator, and may not leave the window,
until detached.  Another press of the middle button toggles the pointer
status to detached.

Maybe you will be trying to find the button labelled `EXIT'. Don't
worry, there is no such button. To terminate FAST, hold down the control
key and press the middle mouse button.

The `Caught SIGSEGV ... ' messages (Sun only) are simply there for
debugging purposes and occur during normal operation.  If the arguments to
signal handlers were documented properly, those messages would be
present in Linux as well (see file TODO).

3.3 Command Line Options

   -a <file>	set disk A file name. E.g. -a /dev/fd0 sets the physical
   		floppy drive to be drive A. The default name is "diska".
   -b <file>	set disk B file name. Using the same name for both drives
   		is discouraged. The default is "diskb".
   -4		start up in color display mode
   -c <file>	name of the cartridge image file (not yet supported)
   -r <file>	name of the rom image file. The default is "rom".
   -m <kbyte>	RAM size (e.g 256, 512, 1024 etc.). The default is 512k.


3.4 Floppy Disks

In most applications, your floppy disks will simply be image files.  Use
dd to create those image files.  The proper disk devices with Linux are
/dev/fd?D360 for single-sided disks and /dev/fd?D720 for double sided
disks (e.g. dd if=/dev/fd0D720 of=diska).

You will find that Atari's operating system has no trouble with HD disk
images as well (/dev/fd?, 1440k).  In fact, TOS supports almost any disk
size and layout (track and sector numbers, cluster size).  A small
program is provided (tools/mkdisk.c), to create large disk images (4 MB
or more, depending on TOS version) for use as a hard disk substitute.
Mkdisk does not support any command line switches other than the file
name of the image file to create, simply edit the program according to
your tastes.  As is, mkdisk is configured to create 4000k disk images.
To build mkdisk, type `make tools' in the FAST directory.

You may access floppy disks directly by specifying the proper device
inode in the command line (e.g. st.i386 -a /dev/fd0).  Note that you
cannot format disks, as the write track command of the FDC chip is not
supported.  Formatting disks will simply not work.  Note, moreover, that
due to neglect and laziness on my part, disks may not be write-protected.

On Sun systems, you will have trouble reading single-sided disks.
Therefore a small programm is provided (tools/rdsingle.c), to read
single-sided disks from device /dev/rfd0 to a disk image file.  Rdsingle
expects the name of the image file as an argument.

3.5 ROMs and ROM troubles

The TOS power-up sequence has a timing loop test, which usually fails if
you are not using an 8 MHz CPU.  For this reason, 16MHz processor
upgrades for the Atari ST usually required patched ROM versions, and for
the same reason, FAST patches the ROM image after it is mapped into
memory.  The patch is rather simple, only a branch instruction is
replaced by a NOP.  However, the right offset within the ROM image, where
this patch has to be applied, is hard coded within FAST for the German
TOS releases 1.0 (1986), 1.2 (1987), and 1.4 (1989).  These releases are,
as far as I know, the only versions released in Germany until 1989.
Other versions may, or may not work, the same goes for other language
versions of the release numbers cited.  Try out and tell me.  If this
turns out to be a problem, future releases of FAST may have some sort of
auto-patch code capable of finding the right offsets for any ROM
version. 

The TOS ROM binaries are NOT included within this distribution. Instead,
an ST executable (tools/TOSRD.PRG) to read the ROMs into an image file
is provided with this release of FAST.  The name of the image file
created is TOS.BIN. The image file will be placed in the current working
directory. The mtools package will not read files from Atari-formatted
disks, mount those floppies (msdos or pcfs file system) instead.

3.6 Compatibility and Emulation Speed

The only known bugs of the 68000 emulator are:

- Missing implementation of ABCD, NBCD, SBCD and STOP instructions.
  If the emulator encounters one of the instructions not implemented,
  FAST will exit with an `assertion failed ...' message.  I never
  encountered this message so far.
- After bus error or address error exceptions the fault address on stack is 
  always set to 0.  Don't worry about this.
- On the 68000 processor faulted instructions are usually cannot be
  restarted, as register contents may have been modified.  The emulator
  has the same problem, plus the program counter may be set wrong.
  Don't worry about this.

A few shortcuts were taken on the subject of timers and interrupts.  The
horizontal blanking interrupt (every 50us) was scrapped, likewise the
raster line counter.  The system timer is not programmable, instead it
will appear every 5, 10 or 20ms.  The system timer is driven by an
interval timer, whose shortest interval is 10ms (on Sun and Linux
systems).  The 10ms timing is the default.  The command line option `-d'
doubles each system timer interrupt (tic), resulting in a pseudo-5ms
interval matching the ST's 200Hz timer speed.  The `-h' option
halves the timer interval (resulting in a 50Hz timer frequency).

The vertical blanking interrupt is raised every 4 tics, resulting in VBL
frequencies of 50Hz, 25Hz (default), or 12.5 Hz.  The ReDraw routine is
called every 4 tics, likewise mouse and keyboard event queues are
emptied every 4 tics.  On fast systems (>100MHz 586) use of the `-d'
option will provide faster screen updates and better mouse
responsiveness.  Look and feel with the `-d' option matches the ST.
You may try `-h' on slow systems, but I do not think you will be happy
with it.

A Dhrystone benchmark program is provided on the boot disk (diska).  Use
values between 5000 and 32767 for the `number of runs' parameter.  The
ST typically executes at 1600 Dhps.  My Linux system (133MHz 586)
typically executes at 2300 Dhps (st.i386 -d), the SPARCstation LX runs
at about 750 Dhps (st.sun4, no -d).  Note that the time measurement of
the Dhrystone program is based on the system timer.  As the default
timer frequency is 100Hz (in contrast to the ST's 200Hz), the
output of the Dhrystone program on FAST without the `-d' option has to
be divided by two.  If your system is very slow, and you have to use the
-h option, the Dhrystone value has to be divided by four.

3.7 Keyboard

The file ikbd.c contains the tables to translate XKeySyms to Atari
scancodes.  Patch here to create versions for non-German languages.


4. Future Work

The author does not plan to do very much on the subject of FAST in the
near future.  If you run into problems drop me a line (see e-mail address
below).  Do not expect to get an answer soon, I am often away from my
mail for several days.

If you want to contribute to FAST, your work will be very much
appreciated.  Just pick any item from the TODO list.  Send comments,
patches and Bug-Fixes to:

	hoenig@informatik.uni-erlangen.de


Appendix A: I/O and device emulation status summary

Devices and Interfaces:

serial port	not supported (yet)
parallel port	not supported (yet)
mouse		supported
keyboard	German keyboard layout only (yet)
floppy disk	2 drives, either physical (device inode) or file.
		Supports almost any disk format using 12bit FATs.
hard disk	not supported (yet). As of now, use of large floppy
		disk files should be sufficient (12bit FAT is the limit).
midi port	not supported
DMA port	uggh!
cartridge	not supported (yet)
display modes	640x400 monochrome, 640x200 2bit, 320x200 4bit.
		The latter two only on color X displays with at least
		4bit deep frame buffers. Pixel doubling with the color
		modes.

Chips and Interrupts

68000		NBCD, ABCD, SBCD and STOP instructions not implemented.
blitter		emulated
WD1772		no read/write track commands
IKBD		no controller execute
RTC		no emulation (yet)
ACIAs		keyboard only, midi dead
AY... (sound)	no emulation (yet)
68901		Software EOI mode only
Interrupts	VBL at 12.5, 25 or 50Hz, no HBL.
		System timer at 50, 100, and 200 Hz.
Memory Size	any size TOS supports
ROM		German versions 1.0, 1.2 and 1.4, other Versions may
		work

(yet) means item included in TODO list.


Appendix B:  Bugs

- Occasional hangups during startup have occurred with the sun version.
