
      ARAnyM (Atari Running on Any Machine)
      version 0.8.7beta released on 2004/02/15


 1) License
 ----------

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Soft-
ware Foundation; either version 2 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the 
 Free Software Foundation, Inc.,
 59 Temple Place, Suite 330, Boston,
 MA  02111-1307  USA


 2) What is this?
 ----------------

ARAnyM is a multiplatform virtual machine (a software layer) for running Atari
ST/TT/Falcon TOS/GEM applications on any hardware with many host operating
systems. The reason for writing ARAnyM is to provide Atari power users with
faster and better machines. The ultimate goal is to create a new platform
where TOS/GEM applications could continue to live forever.

 Features:
 ---------
   o 68040 CPU (including MMU040)
   o 68040 and 68881/2 FPU
   o 14 MB ST-RAM and up to 3824 MB (configurable) of FastRAM
   o VIDEL, Blitter, MFP, ACIA, IKBD for highest possible compatibility
   o Sound (compatible with Atari XBIOS Sound subsystem, incl. TimerA DMA IRQ)
   o Atari floppy DD/HD for connecting floppy image or real floppy drive
   o two IDE channels for connecting disk images, harddrives or CD-ROMs
   o extended keyboard and mouse support (including mouse wheel)
   o direct access to host file system via BetaDOS and MiNT xfs drivers
   o networking using ethernet emulation with a driver for MiNT-Net
   o TOS 4.04, EmuTOS or Linux as the booting operating system
   o runs with FreeMiNT, MagiC, and any other operating system that runs
     also on real Atari computer.
   o Native CD-ROM access (under Linux, other OS: audio CD only), without
     scsi/ide/whatsoever emulation

Important: ARAnyM is not finished. Consider this to be a beta version
and a work-in-progress. Sorry for incomplete and confusing documentation.
Any help with programming/documentation/porting is very welcome!


 3) Installing
 -------------

See INSTALL file.


 4) Configuring and running
 ---------------------------

ARAnyM keeps its configuration in a folder named ".aranym" in your HOME
directory. The config file is $HOME/.aranym/config and is plain text so you
can edit it with a text editor. If the file is not found upon ARAnyM start
it is generated automatically and the options contain default values.
Have a look at the aranym/src/atari/aranymrc.example file for inspiration.

ARAnyM also recognises several command line options - try starting ARAnyM
with the option "--help" to find out more. The command line options have 
a higher priority over the config file. You can use it for temporary change
of ARAnyM parameters or you can even store the command line options setting
to the config file using "aranym --save".

  You also need an operating system:
- either ATARI original TOS 4.04 (found in Falcon030)
- the free TOS replacement called EmuTOS (get the latest version from CVS
  at http://emutos.sf.net/).
- and finally Linux/m68k.

  Aranym expects to find the TOS 4.04 ROM image in $PREFIX/share/aranym/ROM
(if not specified otherwise in the ./configure phase). If you want to keep
the TOS ROM elsewhere then don't forget to update your Aranym config file:
edit the "TOS" line and set the right path to the file ("TOS=/path/to/TOS").

  Aranym also runs with latest EmuTOS. Simply set the "EmuTOS=" config
option to point to your EmuTOS ROM image file. The TOS= is ignored in such
case.

  Aranym can directly load and a boot a Linux kernel from your host drive.
You just need to fill the [LILO] sections with the correct parameters, and
then to run aranym with '-l' or '--lilo' to use it instead of TOS/EmuTOS.
This is currently not usable, due to missing/bugged MMU/hardware emulation.


 5) Connecting harddrives
 ------------------------

You may also want to use a harddisk - either as a disk image or a real thing
from your Atari computer.
Also note that we prepared several disk images for you - visit our download
area at http://aranym.atari.org/

Harddisk images are large files that contain all sectors of an atari harddisk.
They work much the same way as a floppy image. You can simply create a large
file and tell ARAnyM to use it as a harddisk, but you will need to format
it just like a real harddisk before you can actually use it.

Look into FAQ for more details.


 6) Connecting CD-ROM drives
 ---------------------------

You can use IDE emulation, but you can have only 2 IDE devices. So a better
way is to use Natfeat CD-ROM driver, where you can have up to 26 CD-ROM
drives (physical devices A to Z for BetaDOS). The SDL driver allows only audio
CD playing, whereas the Linux driver allows you also data CD-ROM access.

First, See section [CDROMS] in your config file. Each drive letter is a
physical device for BetaDOS, and you can give it any host CD-ROM drive number
(if you have multiple CD-ROM drives on your host machine).

Example:

[CDROMS]
A = 0
..
W = 1
..
Z = 2

Then, on the Atari side, copy the file nfcdrom.bos to your auto folder, and
edit your config.sys file, and add a line like this:

*BOS, \auto\nfcdrom.bos, A, W, Z

You can now use audio CDs with your favorite CD player. If you also want access
to data CD-ROMs, you need an iso9660 filesystem driver. You can find some with
BetaDOS, and add the lines:

*DOS, \auto\iso9660.dos, G:A, H:W, I:Z

To have gemdos drives G, H, I (on your desktop) use the respective A, W, Z
BetaDOS devices.


 7) Accessing data on host OS filesystem
 ---------------------------------------

For accessing data on a host filesystem you can map the host fs to a logical
drive in TOS or MiNT. We have created HostFS BetaDOS driver for use in TOS
and also native MiNT HostFS.XFS driver. BetaDOS is a free and improved
replacement of MetaDOS which in turn was Atari designed AUTO folder patch
that extended the TOS ROM GEMDOS with support for loadable drivers. 

The problem is how to put it on a new harddisk. One way is to use floppy.
Another possibility is to boot the AFROS (Aranym FRee OS) and attach your
disk drive as Slave ([IDE1]).

BetaDOS also needs to know what disk drives you wish to map. Edit the
\AUTO\BDCONFIG.SYS and add there the following line, for example:

*DOS, c:\auto\hostfs.dos, M:M

The M:M stands for that you want to have the M: drive mapped to some Host FS
directory.

MiNT does not need any configuration - just put HOSTFS.XFS to your MINT
folder (\MINT or \MULTITOS) and you're done.

The directory must be put to aranym by the command line argument -d
like:

  "aranym -dm:/opt/home/atari/"

This would map the /opt/home/atari/ to the TOS drive M:\.

For permanent mapping edit the aranym config file, the [ARANYMFS] block
and add the desired path, as follows:

M=/opt/home/atari

More info you'll find in atari/hostfs/README file.

Note: We are planning on writing a tool for BDCONFIG.SYS auto-configuration.


 8) Networking
 -------------

Make sure your host OS is Linux and your Atari OS is FreeMiNT. Then follow
instructions in the atari/network/ethernet/README file.


 9) Keyboard shortcuts
 ---------------------

Keys not found on a PC keyboard:
--------------------------------

Atari Help key - mapped on the F11
Atari Undo key - mapped on the F12

Keys not found on Atari keyboard:
---------------------------------

Page Up key    - mapped as Shift+Arrow Up (usual combination in GEM apps)
Page Down key  - mappped as Shift+Arrow Down (usual combo in GEM apps)

Special keys:
-------------
Pause/Break    - invoke SETUP GUI (ARAnyM on-the-fly configuration)
Shift+Pause    - QUIT ARAnyM
Ctrl+Pause     - REBOOT ARAnyM
Alt+Pause      - enter integrated debugger (only if started with "-D")

PrintScreen    - create a screenshot in actual directory

Alt+Ctrl+Esc   - release the keyboard/mouse input focus so you can use
                 your keyboard and mouse in other host applications.

Scroll Lock    - switch between windowed and fullscreen mode


 10) Troubleshooting
 ------------------

If your Microsoft IntelliMouse doesn't work correctly on Linux framebuffer
console you may want to set the SDL_MOUSEDEV_IMPS2 environment variable to 1.

Example for bash: export SDL_MOUSEDEV_IMPS2=1; aranym


 11) More information
 --------------------

 Read the NEWS file for user visible changes.

 Read ChangeLog for internal changes.
 Look at TODO if you want to help us.

 Join our mailing list for ARAnyM users - the WEB interface for the list
 is at http://bobek.sh.cvut.cz/cgi-bin/mailman/listinfo/aranym-user/

 Visit http://aranym.atari.org/ for latest information and source code.

 For developers we have a developer mailing list and a CVS server.
 For details go to http://aranym.atari.org/


The "Power Without The Price" is back!
