Aranym features and HOWTO
-------------------------

Content:

  0. Preface
  1. General information
  2. CPU and FPU
  3. RAM
  4. Graphics output
  5. Sound
  6. Floppy
  7. Disk devices


This document will explain you all Aranym features and configuration 
procedures as well as important principles of functionality.

Note: This text was written for the main Linux version of Aranym.
      Some features described here may not be available in other 
      Aranym ports. If you use other than Linux version of Aranym,
      please read also additional documentation for your version.

Note: "HOST" means the machine that `hosts' the Aranym virtual machine.
      For most users it's simply their PC or laptop that runs the Aranym.


1. General information

You need to have SDL library installed (http://www.libsdl.org) and 
configured. Required is version 1.2.x or later.

Aranym keeps its configuration in a folder named ".aranym" in your HOME
directory. Also NVRAM cofiguration is stored here. 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 $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.


2. CPU and FPU

Aranym CPU is fully compatible with 68040 and 68882 instruction set. 
Since the address and data caches of original MC68040 are not emulated
there are no compatibility issues with 68000-only dirty written
programs. So forget all TOS patches, cache switchers and FPU drivers, 
these are NOT needed in Aranym.


3. RAM

Aranym provides both ST-RAM and FastRAM (sometimes also called
TT-RAM). ST-RAM size is always 14MB. FastRAM size is adjustable from 
0 up to 4GB. However, in the default addressing mode (called "real") 
only maximum of 128MB addressable space is possible (i.e. only 112MB
for FastRAM). If you want more RAM then you need to reconfigure and
recompile your Aranym binary:

./configure --enable-addressing=direct && make clean && make

In "direct" addressing mode up to 4GB of RAM is possible but this 
mode is a bit slower (that's why it is not the default mode).

In order to let TOS know about the FastRAM you need to start FASTRAM.PRG
program after each Aranym poweron. Best if you put it into your AUTO
folder so it is started automatically during reboot.

Please note that EmuTOS does not need any FASTRAM.PRG - it detects all
available ST-RAM and FastRAM automatically.


4. Graphics output 

4.1. HOST side

Aranym accesses HOST graphics output via the SDL library. This library
is able to use X Windows as well as the framebuffer device. It also uses
HOST hardware acceleration when available. For standard "Aranym only" use 
the framebuffer is the best and fastest solution. You may use also 
X11 if you want to run Aranym in a window (usable for debugging, 
etc.) or if your graphics card is not supported by framebuffer 
drivers. All resolution changes are managed within the Aranym like 
on real TOS machine.


4.1.1. Framebuffer

Framebuffer device is a part of the HOST Linux kernel but unfortunately 
kernels in most Linux distributions do not have this feature compiled in
by default. There are also many graphics cards which do not have
framebuffer driver yet. The generic VESA mode framebuffer driver is not
very suitable for Aranym. In case you are lucky owner of any graphics
card supported by framebuffer (probably all Matrox cards, nearly all 
cards from nVidia, some from ATI and several others) then you should 
recompile your kernel with framebuffer support for your card enabled.

Framebuffer support in kernel is detected automatically by Aranym. Simply
start Aranym from Linux virtual console. No X Windows is required for
running Aranym on framebuffer.


4.1.2. X Windows

Under X Windows just type "aranym" (aranym will run in window) or
"aranym -f" for fullscreen mode.

In fullscreen mode under X Windows Aranym uses resolutions defined in the 
X Windows config file. I.e. if you have defined following modes: 1024x768, 
800x600 and 640x480 then you shouldn't switch into higher resolution 
under Aranym. Lower resolutions are possible but they will be 
displayed with a blac border in near-higher resolution.


4.1.2.1. Mouse and keyboard grabbing

[to be written]


4.2. Aranym side

There are several ways how Aranym generates graphics output.


4.2.1. VIDEL emulation (default, used for booting)

In this mode, Falcon video subsystem is emulated. All modes known 
from Falcon030 are available, including the extended modes. You can
use your favourite screen enhancer (Videlity, BlowUP030, Videl Inside)
to define your own graphics modes. In this case only vertical and horizontal 
resolutions and color depth are important, other parameters are 
ignored.

This Aranym screen output is very slow though, especially in higher 
resolutions because Aranym must convert whole screen data many times 
per second (adjustable - see below) into HOST native format. So it's 
usable mainly for booting and/or installation purposes. This mode 
also allows you to run some not cleanly written (nonGEM) software 
thanks to 99,9% lowlevel compatibility with Falcon030 graphics system.

Switches:

Monitor type (-m) informs TOS in real F030 which monitor type is 
connected. From Aranym point of view it causes only that TOS uses 
different vertical resolutions (200/400 lines for RGB/TV instead for 
240/480 lines for VGA, plus 640x400xTC for RGB/TV). In fact it is 
usable only for experiments with some unclean Falcon software (a few 
programs work only on RGB/TV).

-m1 ...RGB/TV is connected
-m0 ...VGA is connected (default)

Refresh rate (-v <number>) sets how often will Aranym convert atari 
graphics into HOST native format. Default value is 2, which means 
refresh rate 50/2 = 25Hz (fps). Higher refresh rate causes smoother 
graphics but slows down whole emulation.

Boot color depth (-r <number of bytes per pixel>) forces color depth 
durning boot process. Valid values are:

  1...monochrome
  2...4colors
  4...16 colors
  8...256 colors
 16...Falcon TC (16bit)

If not selected then TOS uses the NVRAM setting.

Note: Remember that VIDEL emulation is not usable for serious work 
in GEM and you can never reach full Aranym power when using it!


4.2.2. Direct Truecolor (experimental, obsolete)

This was first working Aranym mode. Thanks to special patch of TOS
the Blitter can draw directly into HOST graphics card memory
without any overhead otherwise caused by converting the TOS bitplanes to
HOST graphics mode. This mode has severe limitations, though. Only Falcon 
truecolor (16bit) can be used, you must use HOST framebuffer output
and big endian capable graphics device is required for correct colors.

This mode is obsolete and is no more a part of Aranym. If you want to 
test it you must reconfigure and recompile your Aranym binary:

./configure --enable-directcolor

Optionally you may enable hardware acceleration:

./configure --enable-blitmemmove
or
./configure --enable-blitsdlblit


After recompiling you need to run Aranym with -t parameter to enable 
Direct truecolor mode. In this case boot color depth (see above) will 
be forced to 16 bpp.

Remember that in Direct TC mode only truecolor mode is displayed 
properly; all other modes will be messed! So make sure you have 
set truecolor mode in your NEWDESK.INF before you try to use direct 
TC mode. But once again, there is really no reason to use this 
obsolete mode.


4.2.3. fVDI + Aranym driver           

This mode is newest, fastest and the only hardware accelerated.
This is the only right mode suitable for real work in GEM.
All you need is to install fVDI with special driver developed for 
Aranym. Following files are needed:

FVDI.PRG ... main fVDI engine created by Johan Klockars
FVDI.SYS ... config file
ARANYM.SYS . fVDI screen driver (the m68k part of it - the HOST native
             part is in the Aranym core)

You can run fVDI from AUTO folder (recommended) or from the 
desktop. For starting from AUTO folder you need to place the FVDI.PRG 
into \AUTO, CONFIG.SYS in the root of the boot drive and ARANYM.SYS 
into \GEMSYS folder (or specify the path in the FVDI.SYS file).

The simplest FVDI.SYS that sets graphics mode into 
resolution 1024x768x16bit should look like this:

----------------------------FVDI.SYS-------------------------
PATH = C:/GEMSYS

booted

01r aranym.sys mode 1024x768x16@75

-------------------------end of FVDI.SYS---------------------

Number after "@" is the refresh rate (in Hz) and is accepted only on 
framebuffer devices in fullscreen.

Look into general fVDI documentation and example FVDI.SYS file for 
more informations.


5. Sound

Not supported yet.


6. Floppy 

You can use floppy image or real floppy drive of your computer.
In both cases reading, writting and formatting is possible.
Aranym also tries to boots from the floppy (like on original Atari).
Both DD (720KB) and HD (1.44MB) are supported.
Larger floppy images known from STonX are supported, too.

In order to get it working you need only to specify path to your floppy 
device or floppy image file in the commandline:

-a /dev/fd0 		... for real floppy device
-a /path/disk.img ... for floppy image

or rather in the Aranym config file:

Floppy = /dev/fd0 (or /path/floppy.img)


7. Disk devices 

There are several ways how to manage harddrives. You can connect 
harddisk from real Atari or clone computer directly into your HOST 
machine and Aranym will be able to use it and even boot from it! 
Another way is to use harddisk images and finally there is 
also the possibility of linking HOST fs directories as a logical disk.


7.1. Using IDE emulation

Aranym can emulate both channels of Falcon IDE interface thus it's 
able to use any disk device (or file) as an harddisk. It uses direct
access to devices so you don't need to have the disk mounted under
the HOST OS; paths to devices are enough.


7.1.1. How to connect a real harddisk

Take a harddisk (from you real TOS machine or any other) and connect 
it into your HOST machine - say as master on the second IDE channel 
(which means that path under Linux will be /dev/hdc).
Then you need to specify geometry of such drive and path in the 
Aranym config file. Important parameters are number of cylinders, 
tracks and sectors per track (usually named C/H/S). There are several 
ways to obtain it. Easiest is to look onto harddrive label where 
C/H/S parameters are usually printed. On the PC you can look into the 
BIOS SETUP. Or under Linux you can use utility called hdparm.

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

and see the output:

/dev/hdc:
 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

The last line is what you need, 1871/255/63 are C/H/S geometry 
parameters. Now open Aranym config file and write here those 
parameters and the path:

[IDE0]
Present = Yes
Path = /dev/hdc
Cylinders = 1871
Heads = 255
SectorsPerTrack = 63
ByteSwap = No

Since there are two IDE channels emulated, you can attach two 
harddisks. If you use only one then disable the second with:

[IDE1]
Present = No


7.1.2. How to use a harddisk image

Harddisk images are large files which are used by Aranym as a real 
harddisk. There are two ways how to make such image. If you want to 
make a copy of your real atari harddisk, then type:

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

That will create an image file of the whole disk connected as 
/dev/hdb.

CAUTION: Be _very_ careful when using the dd command when you are root
as you can destroy your system by a simple typo mistake !

You can also make a empty image file using createdisk.sh utility, 
which is a part of Aranym distribution:

[root@linuxHost /root]# ./createdisk.sh /path/filename size_in_MB

Createdisk then generates empty image file of choosen size and it 
also writes C/H/S paremeters for this image.

Then it is same as in 7.1.1. Only in Path will be a file instead of 
a device:

[IDE0]
Present = Yes
Path = /path/filename
Cylinders = 940
Heads = 16
SectorsPerTrack = 63
ByteSwap = No

Note: C/H/S parameters must be correct even for image files!


7.1.3. Harddisk driver installation

Since TOS itself cannot manage harddisks you have to install 
a harddisk driver. There are several drivers but not all are suitable to 
work with Aranym (due to missing SCSI DMA emulation). Recommended ones
are either Cecile (freeware - http://www.czuba-tech.com) or HDDRIVER
(commercial software - http://www.seimet.de).

If you have connected a real harddisk from any TOS machine and this 
drive is bootable (driver is already installed) then Aranym should 
boot from it like usually. In case you use and empty harddisk or image, 
you have to run driver from floppy and partition it first like on 
real TOS machine.

Note: In HDDriver, SCSI BUS checking must be turned off otherwise 
      the boot process freezes! In order to do it start HDDRUTIL.APP
      (and "locate HDDRIVER.PRG" when not installed), go into 
      menus "setting/devices and partitions" and uncheck all except 
      2.0 and 2.1 (even for an SCSI drive !). If you are going to connect 
      real harddisk with HDDRIVER installed from your TOS machine
      you have to perform this reconfiguration BEFORE you grab it
      from the real machine - otherwise you will get trouble booting
      under Aranym.


7.1.4. CD-ROM

There is also a possibility of attaching real CD-ROM
on emulated IDE channel:

[IDE1]
Present = Yes
IsCDROM = Yes
Path = /dev/hdb

Then you need to install drivers (like SPIN) for the IDE CD-ROM on 
the Aranym side.


7.2. Aranym Fs driver

This driver allows you to map any *already mounted* HOST directory as an 
logical disk drive. This is done using MetaDOS (BetaDOS). Aranym driver
for MetaDOS is available in src/atari/aranymfs/aranymfs.dos.bz2. You can
unpack it and add to the MetaDOS configuration file (config.sys).
The example of config.sys you will find in the same directory as the driver.
The problem is how to put it on the harddisk image you possibly created.
There is no other way than using the floppy (or its image file).

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

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

The M:1 means you want to have the TOS 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:\.

There can be up to 26 mapped drives.

Note: These drives aren't bootable. They are also not designed as 
      alternative to the harddisk images but rather as a way to 
      transfer files between HOST fs and Aranym.


7.3. Aranym.xfs driver for Mint (alpha version!)

This is Mint version of aranymfs driver. Place it into your MINT 
directory; it will map complete HOST fs onto /u/nativefs/ under 
Aranym/Mint.

