
      _____   _________
     /     \      |                  \     /
     |            |                   \   /
     \_____       |    ___    ___      \ /     ( ST on  )
           \      |   /   \ |/   \     / \     ( Unix/X )
           |      |   |   | |    |    /   \
     \_____/      |   \___/ |    |   /     \
      

                       VERSION 0.6 

              (C) 1995 by Marinos Yannikos
               (nino@complang.tuwien.ac.at)
      (http://www.complang.tuwien.ac.at/nino/home.html)

             (C) 2001-2004 by various authors
          (see file AUTHORS for more information)
        URL: http://sourceforge.net/projects/stonx/

	          ALL RIGHTS RESERVED
 THIS PROGRAM IS PROVIDED "AS IS" WITHOUT A WARRANTY OF ANY KIND


      See the file `COPYING' for licensing information

         Last change to this file: April 2, 2001

This file is separated into 4 sections:

  1.  About STonX (general description)
  2.  Frequently Asked Questions
  3.  The Future 
  4.  History

--------------------------------------------------------------------------------

 1. ABOUT STonX
 ##############

Copyright information
~~~~~~~~~~~~~~~~~~~~~
STonX is free software and distributed under the GNU License. Read the file
COPYING for details.

Intruduction
~~~~~~~~~~~~
STonX is a software emulator, which runs on Unix workstations with the X Window
system, and emulates an Atari ST computer. `Software emulator' means, that the
system components, including the 68000 microprocessor, are emulated in software.
This approach has the advantage, that it can be used regardless of the hardware
the emulator runs on. Unfortunately, it also has the disadvantage that it is
very slow.

Why use an emulator?
~~~~~~~~~~~~~~~~~~~~
An emulator's sole purpose is to allow software written for a particular
computer system to be used on other systems. A software emulator in particular
is *not* useful for keeping your old programs while changing your hardware,
except if the new hardware ist several orders of magnitude faster than the
old one. 

What can STonX do?
~~~~~~~~~~~~~~~~~~
As you may have guessed already, it is nearly impossible to emulate a computer
system to its full extent. STonX was initially meant to be a very `low-level'
emulator, meaning that it should be able to deal with hardware register 
accesses and similar things, which it does quite well at the moment. A different
approach would have been to disallow direct hardware access, and support only
"clean" programs, like most GEM applications for example. At this time, STonX
can cope with hardware accesses quite well (see below for limitations), and
I hope to be able to finish the VDI driver for X in the near future, so that
"clean" applications can use the graphics capabilities and speed of your X
display.

Here is a list of the emulated system components:

* M68000 CPU     Everything (I hope) except Trace-Mode and correct bus- and
                 address-error stack frames.

* MFP            Only the necessary parts to get TOS to run (Timer C and
                 VBL). The MFP interrupt priorities are completely bogus,
                 as are the other interrupts in the system, for efficiency
                 reasons and lack of a complete MFP emulation, mainly.

* IKBD           Only keyboard keycodes and (incomplete) relative mouse mode.

* Shifter        ST Shifter, the STE support is not yet complete (the possible
                 word-alignment of the screen would cause problems with the
                 ST-Low and -Mid to ZPixmap conversion routines). 

* Disk-I/O       Still very limited. Since version 0.6.7, there is a real FDC
                 in STonX, at least. A HDC emulator would be nice, but hasn't
                 yet been written
                 However, STonX can map paths of your file system to GEMDOS
                 drives, too. And with the new "stonx.xfs" driver for MiNT,
                 it is even possible to access the whole file system with
                 long file name support!

* Mega ST(E)     Still buggy, haven't had time to correct it. It gets the hour
  Clock Chip     wrong sometimes, and the alarm timer is not implemented (among
                 other things).

* YM2149 sound   Available on several Unix platforms
  chip

* Serial &       Not very useful yet, but enough for testing some
  parallel ports telecommunication software


The Xlib-VDI Driver
~~~~~~~~~~~~~~~~~~~
As of version 0.3, the VDI is already quite usable. Note that the fonts used
are all X fonts (BDF format), and must be installed properly. This is done in
the Makefile (make fonts). The program `tosfonts' extracts the system fonts
from the `tos.img' file (which you're going to need anyway), and installs
them in the `data' subdirectory (see `data/makefonts.sh'). It also installs
Latin-1 versions of these fonts so that you can use them for you XTerm windows!

The Xlib-VDI driver works best on 8bpp X server with private colormap at the
moment. There are still a lot of bugs, especially on high and true color X
servers.


--------------------------------------------------------------------------------

 2. FREQUENTLY ASKED QUESTIONS
 #############################

Q: Why can't I compile STonX on my Computer with Zintorola 86060 processor and
   Sluggix 0.8 Beta O.S.?
A: If you have GNU-C and X11R5/6 for this system, and STonX still won't compile,
   please let me know as soon as possible, I will try to fix it.

Q: How do I leave the emulator `gently'?
A: Press SHIFT-PAUSE under X11 and F12 when using the SVGALib version.

Q: What do all the warnings mean?
A: Some keycodes can not be generated, because no mapping is defined for
   them in `keysyms'. Have a look at that file, and then do a `xmodmap -pke'
   to find suitable keysyms for mapping the missing ST-Keycodes to.

Q: Why doesn't STonX work on my X display?
A: Currently, STonX is very choosy about X displays - it works best on 8 bit
   display with PseudoColor visual capabilities. Building a version for
   monochrome displays might be possible by defining -DMONO=1 in the Makefile,
   but don't bet on it.

Q: Why do the graphics look funny / why are the letters reversed?
A: Because I've merged the modifications for little-endian frame buffers
   without testing it afterwards. Please let me know if this happens!

Q: Why does the emulator window go blank, and then my system starts swapping
   for ages until I finally turn it off?
A: STonX requires approximately 17MB memory, and during the initialization of
   TOS it is quickly accessed linearly, so you should have at least 20MB
   physical memory. You can try to add -DSMALL at the end of the DEF definition
   in the Makefile and recompile everything. This will give create a version of
   STonX which uses only 9MB of memory and emulates a 4MB ST. This option
   has not been tested thoroughly, but seems to work.

Q: What TOS versions does STonX work with? Where do I get TOS images?
A: I tried it with TOS 2.06, other versions might works, too, have a look
   at the file TOS-VERSIONS. TOS versions which support plain STs should work
   with it (i.e TOS 1.06, 1.62, 3.0x and 4.0x will _not_ work).
   You can only use both type of TOS ROM images which begin either at $E00000
   or at $FC0000 in memory (256K ROMs or 192K ROMs).
   TOS is copyrighted, so it would be illegal to distribute a TOS image with
   STonX. To make a TOS image just copy 256K of memory from $E00000 (when using
   TOS 2.0x) or 192K from $FC0000 (when using TOS 1.0x) to a file and put it
   in the STonX directory with the name `tos.img'.

Q: What's `cartridge.img' for?
A: This is an cartridge image which installs the BIOS level disk routines
   and some other TOS patches.

Q: How do I get the emulator to load a program?
A: The emulator can't deal with single programs, only with disks and disk 
   images. If you want to load a disk in a format your Unix box can read,
   you can try the option -disk a:/dev/rfd0 (or replace /dev/rfd0 with
   whatever designates the raw floppy disk device on your system) to load
   directly from disk. This works on Suns. If you want to load a disk
   with a strange format (10 or 11 sectors etc.), you need to make a disk
   image on the ST, and load that disk image onto your Unix disk. To make
   a disk image, copy all sectors from the disk to a file (e.g. sectors
   0-1599 on a 80/10/2 disk). Then, use the option -a:File (replace File with
   the name of the disk image). You can also map several files/disks to 
   TOS drives at the same time, e.g. by using -c:File for drive C. Remember
   that you always map something to drive A though.

Q: Program XXX doesn't run, what should I do?
A: If the program is known to run with the TOS you are using with STonX, 
   and if it doesn't (or shouldn't) use any of the system components not
   yet emulated (see section 1), and if you're getting a 2 bomb bus error,
   it probably accesses a memory location which is not documented, but 
   exists in STs. Please rebuild STonX with -DDEBUG=1, run the program
   again, wait until the crash, and look at the end of DEBUGFILE for a
   message like "pc=<A> sr=<B> BUS ERROR -> <C>". At the previous line,
   there should be a description of the offending memory access. Please
   inform me about it! Note that you're looking at the wrong BUS ERROR
   message if you got 2 bombs on the screen and <C> above does not begin
   with `2'.

Q: Why are the locations of the ST and X mouse cursors different?
A: Because the emulator has (at the moment) no way to tell where the
   emulated system keeps its mouse cursor positions in memory. When you
   enter the emulator window, you can freeze the ST mouse cursor with the
   right mouse button, move to it with the X cursor, and press the right
   mouse button again to "pick it up".
   > This should be fixed in the newest version and no longer occur! <

Q: Why do some keys seem to 'hang' e.g. in Megaroids?
A: Because the interrupt priorities are bogus, and in some cases data from
   the IKBD may be lost. 

Q: Why can't the mouse be switched off (e.g. in games)?
A: Because the emulated IKBD doesn't (yet) understand any commands

Q: Where can I get the newest version of STonX? 
A: Probably at http://sourceforge.net/projects/stonx/
   Don't bet on it though! :-) 

Q: Why do benchmark programs show much better values than what they should?
A: Because Timer C, which is often used for measuring time, is running at
   a lower frequency than the usual 200Hz. Look at the output to stderr when
   starting STonX, it will tell you the actual frequency. If it is e.g. 50Hz,
   the values reported by benchmark programs will be 4 x higher than they
   should be.

Q: When will the VDI driver be finished?
A: If I knew the answer, I'd probably never have started... :-)

Q: What can I do to speed up the development of STonX?
A: You can join the STonX development crew at Sourceforge!

--------------------------------------------------------------------------------

 3. THE FUTURE
 #############

Things left to do:
- Finish the VDI driver
- Speed up the emulation with little-endian hosts
- Optimize a bit more
- Complete the IKBD emulation (esp. Joystick)
- Fix the bug in the clock chip emulation
(etc. etc.)

