Programs incompatible with EmuTOS
=================================
This is a list of programs that have program bugs or shortcomings that
prevent them from running properly with EmuTOS, and whose problem has
been definitively identified.  It is mainly intended to prevent these
programs from being added to 'bugs.txt' in the future.

Program: STOS games
-------------------
Error: joystick and/or keyboard input doesn't work.

Bug analysis:
STOS Basic compiler routines check for input using undocumented and
TOS-specific locations.  Programs using these routines work only with
specific TOS versions, and not with EmuTOS.  STOS fixer may be used to
fix these programs.

Program: Awele v1.01
--------------------
Error: mono desktop colours are inverted after exiting program.

Bug analysis:
This version of Awele was compiled with PureC and linked with a very
early version of Windform.  During WinDOM initialisation, malloc() is
called to allocate an area to save the palette in.  However, although
malloc() returns the pointer in A0, the WinDOM code assumes it is in D0.
As a result, an area of low memory is pointed to, which is overwritten
during Awele execution.  At program termination, the palette is restored
from the overwritten area, resulting in the error seen.

Program: Cameleon
-----------------
Error 1: program exits immediately when 'Start game' is selected.

Bug analysis:
The program requires an STe.  In order to determine whether its's
running on an STe, it checks the contents of location 0x995 (hardcoded).
On Atari TOS, this is where TOS initialisation happens to store the _MCH
cookie but this is *not* how Atari says you should locate it (and it's
not where EmuTOS stores it).

Error 2: program crashes with a Trace exception on any exit.

Bug analysis:
During startup, the program switches to supervisor state via the Super()
system call.  Subsequently, the supervisor stack overwrites the program's
user stack.  On exit, the user stack pointer is restored and during this
a corrupted value is loaded into the SR, causing a trace excpetion.

Program: (VDI) Invaders and Anduril
-----------------------------------
Error: keys to move an object are ignored (in Invaders, the '-' key; in
Anduril, the 'h' & 'j' keys)

Bug analysis:
Both programs were written by "M.Dheus" who found that the most recent
key input from the keyboard was stored at offset 0x6d from the address
returned by Kbdvbase(), and used that to read the keyboard.  This was
never documented by Atari, but was apparently true for all versions of
TOS 1.  However it is not true for TOS 2, 3, or 4 (or EmuTOS).

Program: Ramses
---------------
Error: panic

Bug analysis:
Program calls the Line A initialization $A00A and gets the routine
vectors in a2.  It gets the address of _v_hide_c, then starts doing
undocumented things with the bytes of the actual routine:
    https://sourceforge.net/p/emutos/mailman/message/30605378/

Program: STVidPlay
------------------
Error: "Error in getting file location"

Bug analysis:
Program looks for a specific 2-byte sequence in the hard disk driver
code pointed to by hdv_rw ($476).  If it doesn't find that sequence
within bytes 6-48 (or thereabouts) of the start of the driver, it
gives the error message.

Program: Cubase Lite
--------------------
Error: panic

Bug analysis:
On TOS 1.62 etv_timer vector is a delegate to an internal private
function.  Cubase Lite tries to guess the address of that private
function in an undocumented way, which crashes on EmuTOS.  (Somebody
could write a loader or TSR to change the etv_timer function so that
Cubase will not crash.)

Program: Reservoir Gods games (Bugger, Bunion, SkyFall, Sworm)
--------------------------------------------------------------
Error: panic

Bug analysis:
Games use an undocumented TOS4 vector for keyboard input instead of
accessing kbdvec correctly.  This causes EmuTOS to panic.
This can be worked around with the following hack.prg:
	http://sourceforge.net/mailarchive/message.php?msg_id=26841274

Program: OMIKRON.BASIC V3.01 (interpreter)
------------------------------------------
Error: Panic (bus error) during start

Bug analysis:
The program relies on undocumented internal TOS variables at several
points.  First, it expects A0 upon return from Mediach (BIOS function)
to point to wplatch (floppy write protect latch variable).  On EmuTOS
A0 is 0 and hence a bus error occurs when the program wants to modify
that variable.  Second, it parses the bytes of the 0xA00A (hide cursor)
line-A routine to get the address of a variable reflecting the internal
state of the mouse cursor.  This is done with the same code used in
"Ramses" (see above).  This also fails on EmuTOS, resulting in another
bus error.  There may be more accesses to undocumented variables.
