manual
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.
You need to have 
SDL library installed and
configured. Required is version 1.2.10 or newer.
ARAnyM keeps all its configuration files in one folder. Under linux and most other operating systems this is ".aranym" in your HOME directory. For MacOS X it is Library/Preferences in your HOME directory. The NVRAM setting and the keymap file are stored in that directory as well. These files are normally named config, nvram and keymap or org.atari.aranym.config, org.atari.aranym.nvram and org.atari.aranym.keymap in case of MacOS X. The configuration file is in plain text so you can edit it with a plain text editor. If the file is not found upon ARAnyM startup then it is generated automatically and the options contain default values. Have a look at the aranym/doc/config file for inspiration.
A hint to path descriptions inside the config file. Generally four types of paths are supported, an absolute path description (starting with / or a drive letter for Windows), a relative path description to the current folder ARAnyM was started in, a HOME relative path starting with ~/, and a data folder relative path starting with */, which means $PREFIX/share/aranym/ for linux and most other operating systems and Library/Application Support/ARAnyM in case of MacOS X (recommended).
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:
- ATARI original TOS 4.04 (found in Falcon030)
- the free TOS replacement called EmuTOS
- Linux/m68k (best in Debian/m68k)
On the top of TOS 4.04 or EmuTOS you can boot into MagiC or FreeMiNT, ARAnyM support for MagiC is unoficial, though (but its latest version 6.20 does work in recent ARAnyM pretty well).
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.
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.
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.
For the maximum power you can use JIT compiler that translates the m68k code to x86 code on-the-fly. It is supported only on GNU/Linux, MS Windows and MacOSX (Intel) now. You must enable it before compilation:
$ ./configure --enable-jit-compiler
And also in your ARAnyM config file, section [JIT]:
JIT = Yes
Other interesting lines in the ARAnyM config file are:
JITFPU = Yes
Set to No when you have problems with FPU. We have reported some problems with one library (lame.slb)
JITCacheSize = 8192
Cache size for translated code in kB. Don't forget - bigger cache is good only if you have enough memory.
JITLazyFlush = 1
I think that the best description has Gwenole Beauchesne:
The solution I came up with is what I called "lazy cache flushing" (oops, well s/flushing/invalidation/ ;-). In that case, the whole cache is kept but the entry points are mapped to a special prologue code that will perform a checksum on the basic block, the next time it is called. If checksum matches, the code is kept and revived, otherwise it needs to be retranslated.
For everybody - only in some very abnormal situation could be a problem with "lazy cache flushing".
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.
ARAnyM uses several different methods of synchronizing its internal
time with the host time. The most precise one is the "RTC" method that
is available on Linux and is compiled in by default. Unfortunately, by
default most Linux systems do not allow ARAnyM to configure the
''/dev/rtc'' appropriately so you need to adjust its access rights and
also increase maximum frequence an user application can set. There is a
very good documentation about the required steps over at MythTV wiki.
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.
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.
Under X Window system 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 black border in near-higher resolution.
It is now possible to render the Atari screen using OpenGL. In the [OPENGL] section of the config file, you can choose width, height and bpp of the OpenGL screen. The Atari screen will be zoomed/stretched accordingly. You can also disable/enable linear filtering for the atari screen.
Please see Architecture of ARAnyM video subsystem for technical details.
There are several ways how ARAnyM generates graphics output.
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 ) 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 ) forces color depth during 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!
In the aranym config file, you can also choose to enable the 'autozoom' feature. It allows ARAnyM to zoom/strech the atari screen to fit the size of the host screen. This is specially useful on Linux with vesafb, which is not resizable.
Examples for a 320x200 atari screen on a 1024x768 host screen:
The atari screen is centered on the host screen. (zoomcoefx=320/320=1, zoomcoefy=200/200=1)
The atari screen is zoomed to 1024x768. Not all atari pixels look the same, due to the non-integer zooming coefficients. (Some are 3 pixels wide, others are 4 pixels wide). (zoomcoefx=1024/320=3.2, zoomcoefy=768/200=3.84)
The atari screen is zoomed to 960x600, centered on the host screen. All atari pixels look the same, due to integer zooming coefficients. (zoomcoefx=int(1024/320)=3, zoomcoefy=int(768/200)=3) Note: autozoominteger is automatically disabled if the atari screen is bigger than the host screen.
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:
main fVDI engine created by Johan Klockars
configuration file
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:
PATH = C:/GEMSYS
booted
01r aranym.sys mode 1024x768x16@75
The number after "@" is the refresh rate (in Hz) and is intended to be used only by framebuffer devices in fullscreen (currently this value is not used).
Look into general fVDI documentation and example FVDI.SYS file for more information.
[to be written]
You have several choices to have audio output from Atari applications to the host audio device:
Put the atari/sound/zmagxsnd.prg to your AUTO folder and Aniplayer (after switching to XBIOS in its Sound Config dialog) should play all sounds nicely!
ARAnyM now emulates Falcon audio DMA emulation. Beware that it is not accurate so the emulation could crash an application using audio DMA to replay samples.
ARAnyM can send the MIDI output to a file (or raw midi device) or to a sequencer device.
[MIDI]
# Type of MIDI port emulation:
# none -> No output
# file -> Output to file or raw device
# sequencer -> Use /dev/sequencer midi device under Linux
Type = file
# Output to file, filename, or raw device
File = /tmp/aranym-midi.bin
# Output to Linux /dev/sequencer device
Sequencer = /dev/sequencer
On Linux, if your audio device does not support a real MIDI audio
output, you can use Timidity as software player. See
http://hatari.sourceforge.net/docs/alsa-midi.txt for more information.
In this case, use Type=file, and File=/dev/snd/midiC?D? to hear MIDI
audio.
You can use floppy image or real floppy drive of your computer. In both cases reading, writing 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, in [GLOBAL] section:
Floppy = /dev/fd0 (or /path/floppy.img)
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 or single partition images and finally there is also the possibility of mapping HOST fs directories as a logical disk. Also note that we prepared several disk images for you - visit our download area at https://aranym.github.io/download.html
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.
ARAnyM can emulate both channels of Falcon IDE interface thus it's able to use any disk device (or file) as a 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.
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.
$ cat /proc/ide/hdc/geometry
physical 62016/15/63
logical 3876/240/63
The line with "physical" is what you need, 62016/15/63 are C/H/S geometry parameters. Beware of the hdparm utility which gives you only the "logical" C/H/S which is not really what you need.
Now open ARAnyM config file and write here those parameters and the path:
[IDE0]
Present = Yes
Path = /dev/hdc
Cylinders = 62016
Heads = 15
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
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:
$ 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 create a empty disk image file in the SETUP GUI. Press Pause (or run "aranym --gui"), specify the disk image size and click on the Generate button. The current fileselector is unable to specify an unexisting filename unfortunately (this must be fixed), so for the time being please point it to an existing file that you don't mind get destroyed.
Then the disk image must by partitioned and the partitions must be formatted. Plain old AHDI could do that, I hope. I myself use HDDRIVER as I bought it.
Also please note that EmuTOS < 0.8.6 doesn't handle partitions larger than 255 MB (but newer versions do).
Then it is same as in previous section. 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!
Since TOS itself cannot manage harddisks you have to install a harddisk driver. 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.
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. However, if you were using some special HW drivers, like e.g. Afterburner, Centurbo or NOVA/Rage gfx card drivers, you want to disable them. So try the first boot with Ctrl held down (AUTO folder programs are not executed then).
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.
Single partitions are better in several aspects over Atari harddrives:
- much faster access to data (direct access, not via IDE emulation)
- no problems with CHS geometry, size is autodetected and that's enough
- no need to partition it and can be formatted by Host OS tools
- no Atari harddisk driver is needed
- partition can be mounted on Host OS (Linux) for direct access to files
There is only one drawback - single partitions are supported in EmuTOS only (and FreeMiNT if booted from EmuTOS), so if you still prefer TOS 4.04 this is not for you (yet, as I am working on NF-XHDI driver for TOS).
Example of creating a single partition image in Linux Host OS and working with it:
# create 16 MB disk
$ dd if=/dev/zero of=/tmp/mydisk.img bs=1M count=16
# format it
$ /sbin/mkdosfs /tmp/mydisk.img
# mount it
$ sudo mount -t msdos /tmp/mydisk.img /mnt -o loop=/dev/loop1
# copy files there
$ sudo cp files* /mnt
# unmount it
$ sudo umount /mnt
# add to ARAnyM in the config file
[PARTITION0]
Path = /tmp/mydisk.img
Present = Yes
PartID = $6
ByteSwap = Yes
ReadOnly = No
and now you can start ARAnyM with EmuTOS (and FreeMiNT) and access this new drive. Plain TOS doesn't support it (yet), unfortunately.
You could of course format the mydisk.img with a different filesystem, use "mke2fs" for ext2 (and change the PartID to $83). Or, you could even format it with Atari GEMDOS filesystem using "mkdosfs -A" (changing the PartID to "BGM").
And last but not least - you could access selected partitions on your real harddrive this way. Just set the Path to /dev/hda2, for example (and set correct PartID) and ARAnyM will access second partition on your real harddrive directly.
List of most useful partition IDs follows:
| Value/ASCII character string | Type |
|---|---|
| GEM | Atari FAT16 (up to 31 MB) |
| BGM | Atari FAT16 (BigGeM = more than 32 MB) |
| LNX | Atari Linux (also "MIX" as Minix or "RAW" are supported) |
| $6 | DOS FAT16 in IBM PC format |
| $83 | Linux in IBM PC format |
For this new feature you need ARAnyM 0.9.0+ and up-to-date EmuTOS.
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 (MetaDOS (c) ATARI was AUTO folder patch that extended the TOS ROM GEMDOS with support for loadable drivers - but it's buggy so use BetaDOS instead!).
ARAnyM driver for BetaDOS is available in atari/hostfs/hostfs.dos.bz2. You can unpack it and add to the BetaDOS configuration file (bdconfig.sys). The example of config.sys you will find in the same directory as the driver.
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]).
As you setup the bdconfig.sys (e.g.):
*DOS, c:\auto\hostfs.dos, M:M
The M:M 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.
For permanent mapping edit the [HOSTFS] section in ARAnyM config file. The syntax is = host path [:]
M = /opt/home/atari
O = /usr/src:
The trailing colon in the /usr/src: (example above) instructs the HostFS driver to switch the filesystem on the O:\ to full case-sensitivity mode, i.e. "ARAnyM" will be a different file than say "aranym" or "ARANYM". Normally (=without the colon) the HostFS filesystem is case-insensitive + case-preserving (like on MS-Windows) with a special feature of converting newly created ALLUPPERCASE filenames to lowercase (handy for copying from TOS FAT drive to HostFS drive).
This is Mint version of ARAnyM HostFS driver. Place it into your MINT directory; it will map the host fs to logical disks automatically.
There is an option to compile FreeMiNT kernel which includes the hostfs.xfs functionality built-in and therefore is able to boot from the host OS filesystem directly (similarly to other emulators like e.g. MagiCPC).
This is the freemint/sys/KERNELDEFS section to build such mintara.prg:
ifeq ($(kernel),ara)
MINT = mintara.prg
CPU = 020-60
KERNELDEFS = -DARANYM -DM68040 -DWITH_HOSTFS -DBOOTSTRAPABLE
MODULEDIRS = xfs/hostfs
endif
Such kernel can then be configured to be started directly by EmuTOS in its boot sequence just before a regular AUTO boot would happen by setting the parameters in your aranym config file shown below. Such setup would then boot FreeMiNT directly using the ''path/to/mint/boot'' folder as its bootdrive contents.
[GLOBAL]
EmuTOS = path/to/emutos/etos512k.img
Bootstrap = path/to/freemint/mintara.prg
BootstrapArgs = DEBUG_LEVEL=1 BOOT_DELAY=0 MEM_PROT=NO
BootDrive = C
[HOSTFS]
C = path/to/mint/boot
If you want to use image-files along with the hostfs there is one major difference between the compiled-in hostfs and the external .xfs:
When the hostfs is built-in into the kernel itself it replaces any previously mapped drives (basically allowing HDD image/HOSTFS partial combination config) which become inaccessible at that point.
When started as a .xfs module (not built-in) it keeps the previous kernel established mappings intact and neglects HOSTFS mappings that collide.
In practice: If drive X: is a partition from an image-file and also configured to come from hostfs, the image-partition supersedes the hostsfs-partition if hostfs is external (.xfs), and the hostfs-partition supersedes the imagefile-partition if hostfs is compiled in.
This is important especially for drive C: when it is configured to come from hostfs (which is only possible for internal hostfs), the first partition from IDE0 will be unusable.
The networking in ARAnyM is not an easy topic because there are several different ways you can hook up your virtual machine to the network and you need to choose the right one for your environment.
I would say that the first question is whether you're on a LAN with spare IP addresses or if your host computer has a single public IP and is hooked up to internet directly.
For LAN setup, you probably want your ARAnyM to appear on the LAN just like any other machine so others can ssh, ftp or telnet into it. There are two possible ways: either you can use bridging or proxy-arp. In a broad sense both are bridging, but arp proxying works at the IP level and the host acts as a gateway, while bridging connects to ethernet networks, which means all your host network traffic goes through the bridge device.
If you only need IP connectivity then arp proxying is the considerably simpler solution, e.g. it's simple to setup multiple tap devices for multiple emulation instances. Bridging is only really needed if you want to use DHCP or non-IP protocols, but it has also a bit larger impact on the host network.
For single host computer with public IP the problem is that you usually cannot afford assigning another public IP to ARAnyM so you'll want the host computer to hide ARAnyM and to route traffic to it. For this you'll probably want to use masquerading.
Setting up the proxy-arp is very easy. Let's assume that the host computer's IP address is 192.168.0., the netmask is 255.255.255.0, and that the address 192.168.0.114 is free to use for the emulated machine:
[ETH0]
Type = ptp
HostIP = 192.168.0.5
AtariIP = 192.168.0.114
Netmask = 255.255.255.0
Then the 'aratapif' is to be setuid root and located in $PATH and the tun/tap modules must be loaded (see the documentation.txt and the README in the ethernet folder). Then you can enable the proxy-arp with the following commands (as root):
$ echo 1 >/proc/sys/net/ipv4/ip_forward
$ echo 1 >/proc/sys/net/ipv4/conf/tap0/proxy_arp
$ arp -Ds 192.168.0.114 eth0 pub
$ route add -host 192.168.0.114 tap0
After launching ARAnyM and loading FreeMiNT (with the nfeth.xif driver) you just start my nfeth-config.sh script and it will run the following two commands in FreeMiNT:
$ ifconfig eth0 addr 192.168.0.114 netmask 255.255.255.0
$ route add default eth0 gw 192.168.0.5
And that's it. Now ARAnyM is connected to your LAN with IP 192.168.0.114 and it's fully accessible. It can of course connect to any other machine and also access the internet via our company gateway.
Bjoern Spruck has contributed a piece of shell script that should set up the Linux Host OS' networking for ARAnyM in the masquerading mode:
#/bin/bash
#
# All this should be done as root
#
# Load tun/tap module
modprobe tun
#
# change rights to suid for cause aranym is calling it
chmod +s /usr/local/bin/aratapif
#
# init ip-masquerating
#
/usr/sbin/iptables -D POSTROUTING -t nat -s 192.168.0.0/24 -d ! 192.168.0.0/24 -j MASQUERADE >& /dev/null
/usr/sbin/iptables -t nat -s 192.168.0.0/24 -d ! 192.168.0.0/24 -A POSTROUTING -j MASQUERADE
#
# enable ip-masq
#
echo 1 > /proc/sys/net/ipv4/ip_forward
This script needs to be started as one of the last things in your Host OS boot. Obviously the chmod is not necessary to call each time, it's there just as a reminder I guess. And the last "echo 1 >" is superseded in modern Linux distributions by other methods. But using it doesn't hurt.
Recently Standa developed a new method called Bridging that allows ARAnyM to get its own IP address and to act like a regular machine on your LAN. For Bridging setup enter this in the ARAnyM config file:
[ETH0]
type = bridge
tunnel = tap0
HostIP = 192.168.1.3
AtariIP = 192.168.1.2
Netmask = 255.255.255.0
At last you need to configure the IP address, route and netmask on the FreeMiNT side. For that I developed the 'nfeth-config' tool that can read the ethernet setting from the ARAnyM config file. As of ARAnyM 0.8.11 this requires FreeMiNT 1.16.0+ with NatFeat support. You can simply run the 'eth0-config.sh' shell script during FreeMiNT boot up and it will set up the eth0 interface properly.
Warning: The HostIP configuration entry should perhaps be named GatewayIP as this is the real meaning for both Ptp and Bridged networking modes. The eth0-config.sh uses that entry to set the default route.
My experience shows that the bridging is real easy to get working using the 'arabridge' script. Or even easier, follow (as root) this step by step HOWTO.
Let's say we want to hook the ARAnyM to the 'eth0' interface:
- note ip, netmask and route of eth0
$ /sbin/ifconfig eth0
$ /sbin/route
Say eth0 had IP address 192.168.0.42 with netmask 255.255.255.0 and default route was set to 192.168.0.1.
- shut down eth0
$ ifconfig eth0 0.0.0.0
- create tap0
$ modprobe tun
$ tunctl -t tap0 -u <your_loginname>
- create bridge
$ brctl addbr br0
- add eth0+tap0 to the bridge
$ brctl addif br0 eth0
$ brctl addif br0 tap0
- set ip and netmask of br0 to be same as was the eth0
$ ifconfig br0 192.168.0.42 netmask 255.255.255.0 up
- restore default route
$ route add default gw 192.168.0.1 br0
and that's it. Problems could arise if firewall is running on the same host because the eth0 basically disappears (is replaced with the br0) though it's still possible to fix the firewall setup afterwards.
I have updated the arabridge script, it now works well in Debian. Make sure you edit the USER, NIF and maybe also the TAPS and BRIDGE variables.
First, install the
uml-utilities Debian
package. In the examples below replace the joy in the
''tunctl_user'' line with your real login name. You also want to add
yourself to the uml-net group by executing ''adduser joy uml-net''
(again replace joy with your real login name). And obviously
eth0 in the examples below is your host computer networking
interface so replace it if you use a different interface. Note that
''aratapif'' should not be necessary at all.
''/etc/network/interfaces'':
iface tap0 inet static
address 192.168.1.133
netmask 255.255.255.252
tunctl_user joy
uml_proxy_arp 192.168.1.134
uml_proxy_ether eth0
This creates a mini network within the LAN. The "192.168.1.132-135" should be a set of free IP addresses in your LAN. The mini network consists of a range of four IP addresses, where 132 is the network address and must be divisible by four, 133 is the host IP address, which also acts as the gateway for ARAnyM, 134 is the IP address used by ARAnyM and finally 135 is the broadcast address for this mini network.
Then ip_forward in /etc/sysctl.conf has to be enabled, so that ARAnyM sees the rest of the network. Simply add the following line to ''/etc/sysctl.conf'':
net.ipv4.ip_forward=1
ARAnyM config:
[ETH0]
Type = ptp
Tunnel = tap0
HostIP = 192.168.1.133
AtariIP = 192.168.1.134
Netmask = 255.255.255.252
Roman Zippel says that he tried the proxying also with "Type = bridge" and then aranym wouldn't call aratapif and everything still worked fine. So the following config works, too:
[ETH0]
Type = bridge
Tunnel = tap0
The kernel will print the default IP numbers, which may be a bit confusing, but they aren't actually used.
Install also bridge-utils.
''/etc/network/interfaces'':
auto eth0
iface eth0 inet manual
auto tap0
iface tap0 inet manual
tunctl_user joy
auto br0
iface br0 inet dhcp
bridge_ports eth0 tap0
ARAnyM config: Replace the "192.168.1.3" and "255.255.255.0" with your LAN IP addresses and netmask. The "192.168.1.105" should be a free IP in your LAN. The HostIP, AtariIP and Netmask are not needed if you use DHCP client in FreeMiNT or Linux/m68k.
[ETH0]
type = bridge
tunnel = tap0
HostIP = 192.168.1.3
AtariIP = 192.168.1.105
Netmask = 255.255.255.0
In MS Windows ARAnyM provides TAP-Win32 based networking. It can provide the point-to-point or bridged networking just like Linux's one. I didn't hear about ARP-Proxy for Windows so far though.
It is required to install the Win32-TAP network driver. You can download the OpenVPN installer from OpenVPN download page. Just make sure the TAP driver is installed (it is by default).
It is a good idea to rename the virtual TAP network adapter (in Control Panel > Network Connections) and call it ''tap0'' for compatibility reasons.
IMPORTANT: At least on Windows 10 it is mandatory to set Media Status in TAP-Windows Adapter V9 Properties (found in Advanced tab) to "Always Connected" otherwise ARAnyM wont see the interface!
Configure the IP address and netmask of the TAP Connection in the connection properties dialog. We will take the 192.168.5.1 with netmask 255.255.255.0 for example.
Then in the ARANYM config file put an entry like this:
[ETH0]
Type = ptp
Tunnel = tap0
HostIP = 192.168.5.1
AtariIP = 192.168.5.2
Netmask = 255.255.255.0
Tunnel is the name of the TAP device as shown in the control panel / network connections. This allows you to connect to the ARAnyM instance via SSH from your Windows machine.
Configure the active internet connection 'Internet Connection Sharing' to be shared with the ''tap0'' TAP connection. One note here is that the LAN address range cannot be a private address to begin with 192.168.0.xxx. Windows will complain that there is a network already configured for an Internet connection. So if you are behind your own router, make sure the local addresses are something like 192.168.1.x. This way Windows will allow you share the internet connection.
Then in the ARANYM config file put an entry like this:
[ETH0]
Type = ptp
Tunnel = tap0
HostIP = 192.168.0.1
AtariIP = 192.168.0.2
Netmask = 255.255.255.0
Windows XP provide built-in bridge functionality. So you can create a
bridged connection over your active internet connection and the ARAnyM
''tap0'' one. A very nice HowTo has been done for OpenVPN and is
located at OpenVPN web site.
Your ARANYM configuration file needs to reflect the LAN settings, of course.
This way the running ARAnyM behaves like another machine connected to your LAN. You can use e.g. the SpareMiNT's dhcpclient package to lease the IP address from your DHCP server just as your host OS does. Or you can set the static IP address. All just like if you have another box sitting beside your host machine.
On the Mac ARAnyM provides networking based on the TAP drivers for MacOSX. It provides full featured point-to-point networking, that allows Host<->Guest and Guest<->Internet communications.
It is required to install the TUN/TAP Network Drivers which can be
downloaded at MacOSX TUNTAP download page. Install the drivers with the included
tuntap_installer.
Configure your MacAranym config file and modify the ETH0 section as follows:
[ETH0]
Type = ptp
Tunnel = tap0
HostIP = 192.168.1.8
AtariIP = 192.168.1.9
Netmask = 255.255.255.0
MAC = 00:41:45:54:48:30
Set the HostIP and AtariIP to a network that is outside of your normal network range. i.E. if your default network is 172.16.1.x than you may use i.E. 192.168.1.x, or if your normal network is 192.168.1.x you may use i.E. 172.16.1.x or 192.168.2.x addresses.
If you want to examine your current settings, open the "Terminal" application from the Utilites folder in your Applications directory and enter the command ifconfig.
$ ifconfig
From the output you can examine your current IP address range, seek for the entry which contains an inet entry i.E.:
...
en1: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
tunnel inet -->
inet6 fe80::219:e3ff:fed5:d0a0%en1 prefixlen 64 scopeid 0x5
inet 172.16.1.3 netmask 0xffffff00 broadcast 172.16.1.255
ether 00:19:e3:d5:d0:a0
media: autoselect status: active
supported media: autoselect
vlan: 0 parent interface: <none>
bond interfaces: <none>
..
shows that your current network is using en1 with your IP address set to 172.16.1.3.
BTW: If you want to disable ethernet, set "Type=none".
The setup of the network device tap0 is handled by the script aratapif.sh which you find bundled with the downloaded package. This has to be adapted to your personal requirements. Modify the following values (i.E. use TextEdit for this)
- FW_INTERFACE: Defines the interface which is your normal MacOS network device, which may be en0 for a wired RJ45 and en1 for a WLAN connection
FW_INTERFACE=en1
- NAMESERVER: Point this to your normal name server IP address, if you connect i.E. through a DSL router this may be set to the IP address of it.
NAMESERVER=172.16.1.2
If you want to disable DNS forwarding unset
DNS_FORWARD=
After the file is prepared create a directory ARAnyM, if it is not already existent, in your directory Library/Application Support and copy the file into it.
If you use the afros-0.9.5-3, edit the file /etc/resolv.conf and set the Nameserver address to the IP address that you have used above for the HostIP in the ARAnyM config file.
When starting up MacAranym you will be prompted for a password. This is required because network setup need additional requirements that are not available on normal user level. Enter your personal password here.
You can use IDE emulation (see section 8.1.4), 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.
Through USB Native Feature is possible to access the USB devices attached to host computer's bus (except hubs). Virtually from the Atari side we see an USB Host Controller Chip with 2 ports. Inside the Aranym's Setup GUI, there is a new dialog called "USB" where a list of USB devices attached to the host computer is shown, well actually is a list of USB device interfaces. The interfaces of the devices are seen as different devices. For example a printer with a scanner, will be seen as two devices, it's possible to claim them independently. From this list by just clicking on a button the device interface will be attached to the Atari, it simulates a physical USB device plug in. Clicking on the same button again will de-attach the device. It's possible to attach two devices at max. Hubs aren't showed in the list, so it's not possible to attach them. For now there is a limit of 9 USB devices that can be listed in the USB dialog.
Now it's possible to use the FreeMiNT's USB stack in Aranym with a new driver that has been also coded.
https://github.com/freemint/freemint/tree/master/sys/usb/src.km/ucd/aranym/
Under Linux, because some rights issues to make libusb to work properly you should play a bit with udev, i created a new group named araymusers, then joined my user to this new group and added the file ''60-aranym-usb.rules'' to ''/etc/udev/rules.d'' directory, i don't know if this is enough for other Linux distributions.
Create ''/etc/udev/rules.d/60-aranym-usb.rules'' and add the following content:
# udev rules for libusb and aranym
SUBSYSTEM=="usb_device", GROUP="aranymusers", MODE="0660"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", GROUP="aranymusers", MODE="0660"
Following are tested on Windows 10 (1803), other Windows version may differ somewhat.
If you only see your USB keyboard and USB mouse on the Aranym USB dialog and cannot see other USB devices, you may need to "replace" the default libusb drivers with WinUSB drivers. This can be done with a tool called Zadig https://zadig.akeo.ie/
Run Zadig directly, there is no installation for it. You may need to select Display all devices and turn off hub so that all individual devices are seen. In the Zadig window, select the USB device (from the pulldown menu) that is missing from Aranym USB dialog and then click on the small up/down buttons to select the WinUSB drivers. Click Install Drivers button. The WinUSB drivers will be installed and takes few seconds.
Repeat for each USB devices that you want to be available in Aranym.
You do not need to reboot Aranym, you will see the USB devices immediately when you refresh the list (GET device button) on the Aranym USB dialog.
Note: For USB device that are multi-function like printer with scanner, Zadig may display the devices as Device_0, Device_1, Device_2 .... To suss out the device number allocation, go to Advance mode so that you can see the log details. You will be able to find in the log listing the device names to device number. Once you found this, you may edit the name of the device (in the pulldown menu) to something easier to remember.
You can use the power of the host CPU to render OpenGL scenes, instead of using an emulated m68k and its fpu. This is not hardware accelerated!
First, you need to install Mesa and its offscreen rendering part (OSMesa). Compile Mesa using 'make linux' or 'make linux-x86' on Linux, or make 'darwin' on MacOSX.
Then you can configure ARAnyM to use OSMesa, with --enable-nfosmesa --disable-opengl, then make should do its work. ARAnyM should not be linked with your system OpenGL library, otherwise it won't work.
Finally, fill the [NFOSMESA] section in the config file as needed, you can give the complete path to your Mesa libGL and libOSMesa files.
Atari side: just use osmesa.ldg provided in ARAnyM archive, instead of the original one. You can even use it instead of previous mesa_gl.ldg an tiny_gl.ldg. If you are using MiNT, don't forget the nfosmesa.xdd device driver.
There are different libOSMesa libraries for the host: libOSMesa (8 bits per channel, with separated libGL), libOSMesa16 (16 bits integer value per channel, with included libGL) and libOSMesa32 (32 bits float value per channel, with included libGL). You need to adjust the config file this way:
-
libOSMesa:
ChannelSize = 0 /* mandatory */ libGL = /path/to/mesa/libGL.so /* mandatory */ libOSMesa = /path/to/mesa/libOSMesa.so /* mandatory */ -
libOSMesa16:
ChannelSize = 16 /* mandatory */ libGL = /path/to/mesa/libGL.so /* unused */ libOSMesa = /path/to/mesa/libOSMesa16.so /* mandatory */ -
libOSMesa32:
ChannelSize = 32 /* mandatory */ libGL = /path/to/mesa/libGL.so /* unused */ libOSMesa = /path/to/mesa/libOSMesa32.so /* mandatory */
ARAnyM version 0.9.4+ is able to run stock Atari Linux/m68k kernel like it would be running on a Atari Falcon030 with MC68040. You can use normal Atari bootstrap for booting Linux/m68k from TOS or you can boot the linux kernel directly thanks to ARAnyM integrated LILO (Linux Loader). Of course you need the MMU enabled version of ARAnyM (the binary should be named "aranym-mmu").
In order to ease you the experience of Linux/m68k running on ARAnyM I
created two preinstalled disk images: one with Debian 3.1r2 Sarge
available here (113 MB) and
another with testing version of upcoming Debian Etch for download
here (65 MB) (both disk images
updated on 2006/08/26).
I also uploaded one empty disk image (just partitioned and formatted
with ext3 and swap) for those that like watching the install process
running download here (1 MB).
This image is needed as long as the d-i (Debian Installer) does not
contain Atari partition table support. When the d-i starts complaining
simply switch to second virtual console (Alt+F2) and mount the first
partition of the empty disk to /target: ''mkdir /target ; mount
/dev/discs/disc0/part1 /target''
Follow these simple steps to get these preinstalled Debian disk images running on ARAnyM:
-
download
precompiled 2.4.27 Linux/m68k kernel and one of the disk images and unpack them
to say /tmp/ -
set up the ARAnyM config file with 112 MB Fast RAM, IDE disk pointing to the disk image and possibly also networking (see below an example of working config file)
-
for network in linux-m68k make sure your host bridged networking is set up correctly and that DHCP on your LAN is running
-
run ''aranym-mmu -l -c /tmp/config'' and watch the boot (initial messages go to console/xterminal you launched aranym from for easier capture)
-
log into Debian m68k Sarge with "root" (no password necessary)
A tested ARAnyM config file (update path in [IDE0] section to fit your setup and save to /tmp/config):
[GLOBAL]
FastRAM = 112
AutoGrabMouse = No
[LILO]
Kernel = /tmp/vmlinux
Args = root=/dev/hda1 video=atafb:vga16 stram_swap=0 debug=par
Ramdisk =
[ETH0]
Type = bridge
Tunnel = tap0
[STARTUP]
GrabMouse = No
[IDE0]
Present = Yes
IsCDROM = No
ByteSwap = No
ReadOnly = No
Path = /tmp/sarge.img
Cylinders = 2102
Heads = 16
SectorsPerTrack = 63
ModelName = Sarge m68k
modify your config file:
[LILO]
Kernel = /path/to/linux.bin
Ramdisk = /path/to/root.bin
Floppy = /path/to/rescue.bin
Args = root=/dev/ram load_ramdisk=1 ramdisk_size=13000 stram_swap=0 debug debug=par console=tty0 video=atafb:vga2 nolangchooser
Visit
this site
for linux.bin (kernel image) and root.bin (ramdisk image).
modify your config file:
[LILO]
Kernel = /path/to/vmlinuz-2.4.27-atari
Ramdisk = /path/to/initrd.gz
Args = root=/dev/ram load_ramdisk=1 ramdisk_size=13000 stram_swap=0 debug debug=par console=tty0 video=atafb:vga2 debian-installer/framebuffer=false
Visit this site
for linux kernel images (vmlinuz-2.2.25-atari or vmlinuz-2.4.27-atari).
Visit this site
for ramdisk images (initrd22.gz or initrd.gz).
With correct config file you simply start "aranym-mmu -l -N" and that's it.
ARAnyM contains an unified interface for accessing emulator specific features in a "standard" way that is called Native Features. This new standard has been developed in a close cooperation with ARAnyM, STonX, hatari and EmuTOS developers and its main goal was to allow developing universal drivers shareable across all Atari emulators. This NatFeat interface is to be used by operating system drivers only - it is not intended for direct use by regular applications!
If you need to detect that your TOS/GEM software is running on ARAnyM then please check the standard Atari cookie _MCH. While stock Falcon's _MCH cookie value is $30000 and Milan's (as the latest TOS compatible real hardware) _MCH cookie value is $40000, on the ARAnyM this cookie value should be set to $50000 (unless changed in the ARAnyM's config file, but that applies to TOS only, anyway. EmuTOS hardwires $50000).
FreeMiNT 1.16+ contains direct support for NatFeat drivers and is able to use NatFeat debug output for FreeMiNT debug messages. Also EmuTOS naturally supports basic NatFeats.