
Contents:
- Hatari and EmuTOS
- What is EmuTOS
- EmuTOS usage
- EmuTOS compatibility
- Debugging issues with EmuTOS
- EmuTOS compatibility lists
  - Working free/shareware Atari ST demos and games
  - Non-working free/shareware GEM/mono Atari ST games
  - Working free/shareware Atari STE programs
  - "Almost" working color STE games
  - Working TT specific demos
  - Working free/shareware Falcon demos, games and applications


Hatari and EmuTOS
=================

To run the emulator, a TOS ROM image is needed.  EmuTOS, a free
implementation of TOS, is shipped with the official releases of
Hatari.

This tos.img ROM image is identical to the official binary package of
EmuTOS, which is available at the SourceForge website of EmuTOS.  For
downloading other versions or the source code of EmuTOS, please visit
the EmuTOS website.

The tos.img file included with the latest Hatari releases is the
"all languages" etos512k.img from a preceeding EmuTOS release:
- Hatari v1.6.0:
  http://sourceforge.net/projects/emutos/files/emutos/0.8.6/
- Hatari v1.4.0, v1.5.0:
  http://sourceforge.net/projects/emutos/files/emutos/0.8.5/
- Hatari v1.1.0, v1.2.0, v1.3.0, v1.3.1:
  http://sourceforge.net/projects/emutos/files/emutos/0.8.4/
- Hatari v1.0.0, v1.0.1:
  http://sourceforge.net/projects/emutos/files/emutos/0.8.3/
- Hatari v0.95:
  http://sourceforge.net/projects/emutos/files/emutos/0.8.2/

Earlier Hatari binary releases have included one of the smaller
EmuTOS image files.

Note for EmuTOS before 0.8.6 :
  In order to work with Hatari, EmuTOS 0.8.5 and earlier require
  the FastBoot option to be enabled. This is used to skip some memory
  tests (that Hatari doesn't support yet) when EmuTOS try to determine
  the available RAM size.

What is EmuTOS
==============

EmuTOS is a single-user single-tasking operating system for the 32-bit
Atari computers and emulators.  It can be used as a replacement for
the TOS images typically needed today for using the emulators and it is
also running on some real hardware, like the Atari Mega STE and Atari
ColdFire.  All the source code is open and free, licensed under the
GNU General Public License (GPL).  A copy of the GNU GPL can be found
in the gpl.txt file.

EmuTOS has its home at SourceForge:
       http://sourceforge.net/projects/emutos


EmuTOS usage
============

There are various reasons for using EmuTOS instead of the original
TOS ROM images:

* Users who don't have Atari HW or other legal means to obtain the
  original Atari TOS ROMs (for all of the Hatari supported Atari
  versions: ST/STE/TT/Falcon), but would like to try out Hatari and
  see what kind of software the Atari machines had.  EmuTOS gives
  them a legal way to test Hatari with free demos, games etc.

* Users who want to continue using Atari compatible operating systems
  and need an open source replacement of TOS for modifications. Beside
  EmuTOS they typically alse use FreeMiNT, XaAES and fVDI as operating
  system replacements/improvements.

* This includes users of new "Atari" machines like Atari ColdFire project,
  which isn't 100% compatible at HW level to the original Atari machines:
	http://acp.atari.org/

* EmuTOS also allows using ACSI disk images with Hatari TT/Falcon
  emulation, whereas TOS 3 & 4 support only IDE and SCSI disks.
  Hard disk images are needed mainly for running MiNT.


EmuTOS compatibility
====================

These comments apply to EmuTOS v0.8.x.

Many commercial games and applications work fine with EmuTOS. This is
because games (like Bombjack, Nebulus, Oids, Super Hang-On, Turrican,
Xenon...) use directly the hardware which Hatari emulates just fine
and applications use the correct higher level APIs (AES/VDI) for which
EmuTOS has implementations.

EmuTOS AES support is somewhat buggy (mouse clicks and dragging
doesn't always work properly) and VDI support is slowish. Anybody
wanting proper AES/VDI support should install replacement for these,
either the free XaAES + fVDI, or the earlier commercial solutions like
NVDI.

Free games have the issue that they often use the Line-A functionality
which is not supported by EmuTOS[1] unlike AES/VDI.  This is partly a
problem with the tools that they've been done with (for example older
STOS and GFA basic version liked to use Line-A for graphics). There
are also many old demos which use it for convenience.

[1] EmuTOS has some old/partial implementations for some of the Line-A
    functionality, but these are so buggy that they aren't enabled in
    EmuTOS releases except for mouse on/off functionality.

Joystick doesn't work in some (STOS) games that access it through
other means than XBIOS function Kbdvbase() or by hooking into the IKBD
interrupt vector.  They probably use some unofficial system variables
which location depends on the TOS version.


Debugging issues with EmuTOS
============================

To debug problems with EmuTOS, you have to recompile it from the source
after enabling the MIDI debug output in its config.h header file. Then
start Hatari with the "--midi-out /dev/stderr" optio and you will see
the EmuTOS debug output such as calls to missing Line-A functions.

To inspect EmuTOS issues with the Hatari debugger, you'll need symbols
for the EmuTOS image you're using.  If you've compiled EmuTOS with
AHCC[2], you can get suitable symbols with its "-n" linker flag, or
you can use a script coming with Hatari (ahcc-symbols-convert.sh) to
convert AHCC *.map file to "nm" format supported by the Hatari
debugger.

After loading the symbols to the debugger, disassembling the problematic
address should provide more clues for the problem.  Or you can just look
up the program counter value given in the EmuTOS panic message from
the AHCC emutos.map file.

Hatari profiling support can be used to debug OS freezes.  If EmuTOS gets
stuck, just profile it for a while and then ask debugger for a profile
that tells where it's looping and then disassemble that part with symbols
directly in Hatari.  More information on the debugger and profiling is
in the Hatari manual.

[2] AHCC: http://members.chello.nl/h.robbers/


EmuTOS compatibility lists
==========================

The compatibility lists below cater for users who don't have Atari HW
and therefore won't have (legal) version of commercial Atari software
and most likely lack motivation to investigate applications very
deeply (Linux offers better alternatives nowadays for most of that).
I.e. the list skips commercial software and concentrates on EmuTOS
compatibility of freely available games and demos.

Games that are considered good quality & fun, are marked with "*".
All the listed demos are quite OK. Most demos can be downloaded from
http://pouet.net/

First are listed ST demos and games, then STE demos, games and music
applications and last Falcon demos, games and (music) applications.


Working free/shareware Atari ST demos and games
-----------------------------------------------

There are so many freely available color games and demos that from
those only the ones found working with EmuTOS are listed. Often the
non-working ones "Panic" EmuTOS.

Demos:
- 2011 (by Positivity & Sector One, 4kB intro)
- 4getful (by gwEm, 4KB intro)
- 4kker (by Checkpoint, 4KB intro)
- Anomaly (by MMJ-Prod)
- Breath (by Mystic Bytes)
- Coast II Coast (by Sector One, 4kB intro)
- Darktrip (by Legend, doesn't work with >2MB of RAM)
- Dark Side of the Spoon (by ULM)
- Death of the Clock Cycles (by Aggression)
- Dimensio (by Condemned)
- Flashback (by Carebears)
- Frenchies (by Frenchies, 96KB intro)
- Grafik -und Sounddemo (by Eckhard Kruse, font issues)
- Hallucinations (by Reservoir Gods)
- Outline 2008 invite (by DHS)
- Outline 2010 invite (by Checkpoint)
- Overdose (by Aggression)
- Pandemonium (by Chaos)
- Paradise (by Dune Design)
- Phaleon Gigademo
- Posh (by Checkpoint)
- Rebirth (by MMJ production)
- Save The Earth (by Defence Force)
- SillyVenture 2k10 & 2k11 (invitros by Mystic Bytes & Aggression)
- Sommarhack 2011 (invite by DHS)
- Soundtracker (by Equinox)
- ST soccer (intro by Exceptions)
- Stone tower (by FUN)
- Superstar! (intro by Positivity/Dma-Sc/Ukko)
- Sweety (by DHS)
- Twelve (by Paulo Simoes)
- Tut! (by Wildfire)
- Two in One (by DHS)
- Visualize (by Checkpoint)
- YmRockerz musicdisks from "Wave upon Wave" to "Seven"
- Xmas2000 (by Paranoid)

Color games:
- Archon 4KB
- Alien Blockade
- Bellum*
- Bombs Away
- ChuChu Rocket* (Lite version for STFM)
- Clogged Up
- Crapman*
- Dave Munsie games (shareware)
- Entombed
- Flip'em* (4KB puzzle)
- Grav*
- Hackman II*
- Hang About (4KB mountain climbing)
- Haywire
- Hector*
- Jetpac
- Nibe 2
- Nova
- Pengy
- Punt II
- Rockfall*
- Robert in the Fire Factory
- Santafly
- Snowball Fight
- Spacewar
- Starball* (shareware)
- Sweeper
- Tankx*
- Teserae*
- Yak (4KB gridrunner)

Med-rez games:
- Poker solitaire

GEM games:
- 4 Gewinnt* (Connect four)
- Awele v1.02 (in v1.01 menus close immediately after opening)
- Ballerburg* (bug: mouse-over acts like click)
- Biglife*
- Centi
- Chess* (works only from floppy)
- Clicks* (needs wdialog)
- Daleks*
- Dame
- DBWH
- Drachen
- Flipside (fs, othello)
- Gem_mind
- Gnuchess
- Gobang* (needs EmuTOS >= v0.8.6)
- Invers
- Isola
- Kensington
- Magic Stones* (m_stones: tetris, 2x tetris, columns)
- Mars (corewars)
- Mathmaze
- Megaroid*
- Mines*
- Mosaik
- Nethack*
- Orb
- Pacman
- Shanghai
- Sixteen
- Snake
- Solitair*
- Stello*
- ST Concentration*
- Sudoku*
- Tartan* (chess)
- Thor (Othello, unstable)
- Thrust
- Tricky yahoo
- Verrueck (labyrinth)
- Wator (slow)
- WindowBall (breakout)
- Worm farm
- Wormania
- zSudoku

Monochrome games:
- Balloons
- Bounce
- Columns* (needs EmuTOS >= 0.8.6, some text & gfx issues)
- Delta patrol
- Emperor (v1.0 & v1.5)
- Fun Face (playable demo)
- Go UP
- HASCS
- Lasermon (laser "chess")
- Mandala
- MiniGolf* (GFA basic)
- Monkey Business
- Mr Dash
- Poolmono*
- Punssi
- Pyro
- Qix
- Sbreak* (by Mark Overmars)
- Sherlock* (needs EmuTOS >= 0.8.6, some text issues)
- Space war (bug: score missing)
- Wallball

Text games:
- Advent (Colossal Cave)
- Eliza
- Hack
- Larn
- Omega


Non-working free/shareware GEM/mono Atari ST games
--------------------------------------------------

Although there are plenty of color demos and games, the number of
(even remotely fun) free GEM or monochrome games and demos is so low
that for those I list here non-working ones.  Unless otherwise stated,
the issues in them are assumed to be Line-A related (graphics don't
show because they use Line-A drawing functions etc).

GEM games:
- Abalone   (dragging doesn't work)
- Bombs     (mouse clicks almost never work)
- Checkers  (dragging doesn't work)
- Corewar   (programs are shown as white, not with different patterns)
- Dte       (mouse gets stuck)
- Gemamigo* (panic or double bus error)
- Halma     (boxes are left on screen)
- Invaders* (shots go through buildings/shields)
- Patience* (dragging doesn't work, dialog selection persists)
- Risky*    (dragging doesn't work)
- Yams      (mouse clicks don't work)
- Yukon*    (dragging doesn't work)

Games that mix GEM UI and non-VDI drawing:
- Backgam   (line-A bitblit)
- Fishes    (line-A line and filled rectangle)
- Robugs*   (line-A filled rectangle and draw sprite)

Mono games:
- Crystal Caves* (Line-A bitblit and draw/clear sprite)
- Domino	(line-A bitblit)
- Lokomotive	(line-A bitblit)
- MacPan*	(Line-A draw/clear sprite)
- Midimaze*	(joystick doesn't work)
- MineFeld	(Line-A draw/clear sprite)
- Pipeline*	(line-A line and filled rectangle)
- Pling II	(Line-A bitblit and draw/clear sprite)
- Roll X	(line-A bitblit and get pixel)


Working free/shareware Atari STE programs
-----------------------------------------

There are not that many freely available or even commercial programs
that would be STE specific (or even STE enhanced):
    http://atari-ste.anvil-soft.com/html/archivapps.htm

Missing DMA and Blitter support in EmuTOS (XBios functions etc) is
an additional reason why some programs/demos (such as Blittermania)
don't work with it. But following STE specific demos, games and apps
work (mostly) fine with EmuTOS.

Demos:
- 1st Step (by Tobe/MJJ Prod)
- 20 years megademo (by Atari scene collective), issues in some screens
- 20 years Atari STE megademo (by Paradox), some screen don't work
- Again (by Paradox)
- Armada is dead (by Aggression)
- Azed/Jungle demo (by Atari)
- Beat Demo (by Frontline)
- Birdie (by Zeal)
- Blue Period (by Paradox)
- CD-player (by Light)
- Cernit Trandafir (by DHS)
- Core Flakes (by New Core)
- Dynamite (by Unit 17)
- E605 (by Light)
- Ecstacy A (by ICE), breaks at the end
- French Kiss (by DHS)
- Illusion (by Next)
- Gobi Toons (by Dune)
- Grimey (by Reservoir Gods)
- High Fidelity Dreams (by Aura)
- HighResMode (by Paradox)
- Kick my assembler (by Orion), start doesn't look right
- Madness (by Cream)
- Mathematica (by Aura)
- More or Less Zero (by DHS)
- Maxymizer compo 2006 (by gwEm)
- Meshake (by Spice Boys)
- Mind Rewind (by Reservoir Gods)
- MovieSTE (by Tony Barker)
- New Year -94 Intro (by Extream)
- No Monkey (by Tomchi), some extra pixels in first text scroller
- Pacemaker (by Paradox), stops at end-part
- Paracon 6 & 7 remindtros (by Paradox)
- Power Rise (by Light)
- Reanimation (by Syntax)
- Realtime (by MJJ Prod)
- Sinfull Sinuses (by Chronicle)
- Sommarhack (by DHS)
- STE slideshow (by DHS)
- STE Wars (by Tony Barker)
- Summer Delights (by DHS), sound missing
- Sventure intro (by Paradox)
- Vision (by POV)
- XiTEC Presentation (by Omega)

Color games:
- 4K Pacman (bug: background not cleared to black)
- Aerial Combat 3
- Alien Blast (demo)
- Battletris+
- ChuChu Rocket* (full version)
- Dynaplus*
- Frantick
- No Limit II (shareware pinball)
- Obsession* (demo of commercial pinball)
- Operation Garfield
- Pacman on E
- Power Up
- Skulls (shareware "minesweeper")
- Spy 4k
- Stardust* (tunnel sequence demo)
- STEtris
- STrEet Fighter II (incomplete)
- Stupid balloon game
- Substation* (demo)
- Tomtar
- Utopos* (demo)
- Wolfenstein3D v0.8a* (a bit unstable)

STE (enhanced) music applications:
- Blipp Blopper
- Desktracker
- Hextracker
- MaxYMizer
- Octalyzer
- Paula
- Sirius Player

Most of the non-GEM ST tracker & chip music composer programs
work also with EmuTOS too (not just STe ones).

Protracker STE complains about missing DMA.


"Almost" working color STE games
--------------------------------

There are some STE (enhanced) games that would appear otherwise to
work perfectly, but some part of the graphics just don't show.  They
are listed in case someone, someday, starts to fix the EmuTOS line-A
things (mainly bitblt).

- Atari Scene Card Battle (card images don't show)
- Blat (main graphics don't show)
- Breakdance (another scene game, game freezes when playing)
- Mr Boomer (all graphics don't show)
- Kolmik (tiles don't show)
- Pooz (all graphics don't show)


Working TT specific demos
-------------------------

- 256mbrot, Glasstro, Orion-B, Yabt (TT/Falcon intros by ray//.tSCc)
- 4getful (by gwEm, 4KB intro TT-version)
- Adebug 3DTT demo (by Brainstorm)
- TT highres slideshow (by .tSCc)
- XiTEC presentation (by Omega)


Working free/shareware Falcon demos, games and applications
-----------------------------------------------------------

Missing Videl and DSP support in EmuTOS is probably the reason why
many of the demos and games get wrong video mode and their graphics
look completely broken under EmuTOS.  Following Falcon only
demos, games and apps work (mostly) fine though.

Demos:
- A Rh Positive 4k (by tSSc)
- Alive (by Fun Industries)
- Ascii (by Reservoir Gods)
- ATS (by DHS)
- Birdshow
- Blue & Flu 4k (by New Beat)
- DBA Magazine 14 intro (by Lazer)
- Illusion 64 (by Paranoia)
- Game of Life 4k (by Aggression)
- Snowstorm (by Reservoir Gods)
- Terrorize Your Soul (by tSSc)
  - fonts and colors aren't right on all screens
- Virtual City (needs DSP)
- ZZ 9 Plural Z Alpha (by tSSc)

Games:
- Aces High (preview)
- Blum
- Columns by Deadheart (demo)*
- Corsair
- DB 4K
- Dry Egg (needs >4MB RAM)
- FalcTron
- Heretic (lower part of screen flickers, I think EmuTOS screen is too high)
- Impulse (Breakout clone)*
- Lamemine (needs "dummy" DSP mode in Hatari)
- Madtris
- Running*
- Radical Race (demo)*
- Rave (needs "dummy" DSP mode in Hatari)
- SBM v0.8 (Bomberman clone)*
- Spice (Defender clone)*
- Static (Patience by Reservoir Gods)
- Steinbruch
- Tank Blaster
- Toy Man
- Vertical Mayhem (Columns clone)*
- Willie's Adventure (preview)*

Games working with extra hacks:
- Bugger, Bunion, SkyFall, Sworm games by Resorvoir Gods:
  - use an undocumented TOS4 vector for keyboard input instead of accessing
    kbdvec correctly which use causes EmuTOS to panic.  This can be worked
    around with the following hack.prg:
    http://sourceforge.net/mailarchive/message.php?msg_id=26841274
  - with EmuTOS enabling DSP freezes the games right at startup
    (with normal TOS4, DSP is used for background music)

Utilities:
- Cecile hard disk (image) driver

Mostly working applications:
- AceMidi demo (softsynth sounds need DSP)
- FlaySID (sound needs DSP)
- Fractal Playground (parameter input doesn't work)
- Kronos (benchmark)
- Whip! (virtual light machine)

Almost working demos & games:
- Double Bobble 2000, Tautlogy & Tautology II by Reservoir Gods, Nibe:
  - screen is messed, I suspect EmuTOS is missing resolution change function
- Motion (unfinished demo by Aggression)
  - only writer screens work


	- Eero
