
      ARAnyM (Atari Running on Any Machine)
      version 0.0.21 dated 2002/02/12


 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 and under any host operating
system. 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.

Important: ARAnyM is far from being finished. Consider this to be an alpha
version and a work-in-progress. Sorry for total lack of documentation.
And beware - ARAnyM is not yet very usable - some of its features are
unstable and the runtime configuration is not done yet.


 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 recognizes 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 the operating system - either ATARI original TOS 4.04 (found
in Falcon030) or the free TOS replacement called EmuTOS (get the latest
version from CVS at http://emutos.sf.net/).

ARAnyM expects to find the TOS 4.04 ROM image in /usr/local/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" 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.



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

You may also want to use a harddisk - either as a disk image or a real thing
from your Atari computer. Look into FAQ for more details.
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.

ARAnyM comes with a utility called "createdisk.sh" to create an empty harddisk
image file. If you would like to create an image of a real Atari harddisk then
you have two options: either create the image on the Atari (using some disk
tool like Diamond Edge or Diskus) or connect your harddrive to the ARAnyM
machine (say as a slave on the primary channel, so it's /dev/hdb under Linux).

[root@linuxHost /root]# hdparm /dev/hdb

/dev/hdb:
 multcount    = 16 (on)
 I/O support  =  1 (32-bit)
 unmaskirq    =  1 (on)
 using_dma    =  1 (on)
 keepsettings =  0 (off)
 nowerr       =  0 (off)
 readonly     =  0 (off)
 readahead    =  8 (on)
 geometry     = 1871/255/63, sectors = 30064608, start = 0

[root@linuxHost /root]# dd if=/dev/hdb of=/path/to/my/AtariDrive

That will create an image file of the whole disk.
CAUTION: Be _very_ careful when using the dd command as you are root now and
you can destroy your system by a simple typo mistake.
After this you must setup the image file geometry in the ~/.aranym/config file
like the following:
	 
[IDE0]
Present = Yes
Path = /path/to/my/AtariDrive
Cylinders = 1871
Heads = 255
SectorsPerTrack = 63
ByteSwap = No

Note: The Cylinders/Heads/SectorPerTrack values must correspond to the geometry
returned by the hdparm command (see above, the line beginning with "geometry").

If the harddisk was not bootable (or is created as empty) you will want to
install a harddisk driver on it so you could boot from the harddrive.
We tested several harddisk drivers and found the HDDRIVER (once the SCSI bus
scanning is disabled) and Cecile to work OK.


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

This is done by the most clean way it could be. In order to not to patch
the TOS, the MetaDOS (BetaDOS) driver is available in
src/atari/aranymfs/aranymfs.dos.bz2. You can extract it and add to the MetaDOS
configuration file (config.sys). The example you can find in config.sys
in the same directory as the driver .bz2 file.
The problem is how to put it on the harddisk image you possibly created. There
is no other way than the floppy (or its image file).

As you setup the config.sys (e.g.):

*DOS, c:\auto\aranymfs.dos, M:1

The M:1 stands for that you want to have the M: drive mapped to some Host OS
directory. 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:\.

Note: The config.sys edit tool and the aranym config configuration will come
      soon. The MiNT and MagiC .xfs drivers will be programmed in the future.


 7) Keyboard shortcuts
 ---------------------

While the emulator is running, you can quit it by pressing Shift+Break.
And if you started ARAnyM with the debugger option, you can enter
the debugger by pressing Alt+Break.

Press Alt+Ctrl+Esc keys to release the input focus.

F11 is the Help key while F12 is the Undo key.

PageUp/PageDown are mapped to Shift+ArrowUp/ArrowDown which is the
most often used combination for paging up and down in GEM programs.

Alt+PrintScreen grabs a screenshot.


 8) 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


 9) More information
 -------------------

 Read the NEWS file for user visible changes.

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

 Write us at aranym@sophics.cz.

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

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


May the Power Without The Price be with you again!
