ArcEm – The Acorn Archimedes Emulator

Development version (CVS HEAD) Manual http://arcem.sf.net/

This user manual is for the latest version of ArcEm, only available from CVS.

Contents

System requirements

Unix/X Windows

TODO

Microsoft Windows

TODO

Mac OS X

TODO

RISC OS
Amiga

TODO

Installation

Follow the instructions appropriate for your system:

Unix/X Windows

Download the src archive and follow the compilation instructions below. Once compiled copy the arcemrc file to your home directory as .arcemrc. When run there is some output on the console.

Microsoft Windows

Extract the archive and supply a ROM image, the program is called ArcEm.exe. Create a shortcut to this file if you want to add it to your start menu or desktop.

Mac OS X

TODO

RISC OS

Extract the archive to any directory you choose. Once you have a ROM image to use (see below), save it as the file 'ROM' within !ArcEm.

Amiga

Extract the archive to any directory you choose, just add a file called ROM as described below.

Note: Once installed all versions require a ROM image file.

Compiling ArcEm

Follow the instructions appropriate for your system:

Unix/X Windows

The X windows version compiles up using the 'Makefile' contained in the root of the source package. If you have a big endian processor, such as Sparc or PowerPC edit the HOST_BIGENDIAN=no to HOST_BIGENDIAN=yes near the top of the Makefile. Use the following command:

$ make
Microsoft Windows

ArcEm will build under Cygwin. It builds a version which is independent of Cygwin (unlike the previous version of ArcEm for Windows), so you will also need to ensure you have mingw-runtime library installed (from Cygwin setup). Use the following command:

make SYSTEM=win

Additionally, ArcEm will build in Microsoft Visual C 6. Project files are provided for this in the 'vc' directory. There are also project files in 'vc' for Microsoft Studio 2005.

Mac OS X

TODO

RISC OS

ArcEm builds with GCC. You should use the following command:

*make SYSTEM=riscos-single

It is possible to build with Leo White's RiscXLib if you really want to make an X Windows version under RISC OS, but that is beyond the scope of this guide. Finally, it is also possible to cross compile it using GCCSDK. e.g.:

$ CC=/home/riscos/cross/bin/gcc make SYSTEM=riscos-single

The desktop version of ArcEm has not been developed yet, and will not build.

Amiga

You will need the official Amiga OS4 SDK and GCC, then build with the following commands:

stack 500000
make SYSTEM=amiga

It will not compile with anything other than the OS4 includes. GCC 3.4.4 and 4.0.2 are known to work.

Using ArcEm

ROM images

As ArcEm is only a hardware emulator to make it do anything useful you need an operating system ROM. ArcEm has been tested with and is known to work with ARM Linux, RISC OS 3.10, RISC OS 3.11 and RISC OS 3.19. ARM Linux ROMs are freely available, check the website. RISC OS 3.1x ROMs can be extracted from a real Acorn machine using the following commands on RISC OS.

*save :0.$.ROM1 3800000 3880000
*save :0.$.ROM2 3880000 3900000
*save :0.$.ROM3 3900000 3980000
*save :0.$.ROM4 3980000 3a00000

Copy these files to your host operating system, RISC OS 3.1x supports DOS formatted floppy discs so you can use them to transfer the files. ArcEm needs the ROM file to be in one part (rather than the four you just created) so join them back together using the appropriate command for your system:

Unix/XWindows

From a shell prompt:

$ cat ROM1 ROM2 ROM3 ROM4 > ROM
Windows

From a cmd.exe command prompt:

copy /b ROM1+ROM2+ROM3+ROM4 ROM
Mac OS X

TODO

RISC OS

From the command line:

*print ROM1 { > ROM }
*print ROM2 { >> ROM }
*print ROM3 { >> ROM }
*print ROM4 { >> ROM }
Amiga

From the commandline

join ROM1 ROM2 ROM3 ROM4 as ROM

Alternate sources of ROM images

You can download a copy of the RISC OS 3.10 ROM image as a support file from the !A310emu website, it's in the file support2.zip and is called ro310, you should rename ro310 to ROM before using it with ArcEm. Another good source is the 4corn Archive.

Mouse Input

Some of the platforms require specific instructions to let you move the mouse around.

Unix/X Windows

Whilst the Main display window has the focus, press the + key on the numeric keypad to 'capture' the mouse. To 'free' the mouse again for use with the rest of your X desktop press numeric keypad + again.

Windows

Although there is some mouse movement when you move the cursor over the display window, you can use the Unix/XWindows style numeric keypad + toggle to 'capture' and 'free' the mouse for better performance. Currently mouse handling on the Windows build is very poor.

Mac OS X

TODO

RISC OS

The RISC OS version runs full-screen and captures all mouse input until you quit the program. You can quit ArcEm from the menu you can bring up by pressing both Windows keys, or by pressing Alt-Break.

Amiga

The Amiga version runs full-screen and captures all mouse input until you quit the program. You can quit ArcEm from the menu you can bring up with the Left Amiga key.

Using floppies

All the platforms support using .adf format floppy disc images. A disc image is a binary dump of the contents of a floppy disc. ArcEm has no support for directly using the host computers real floppy disc drive.

The basic support for floppy discs is to allow you to have the following floppy disc images in the current working directory of the ArcEm executable:

These are then available under RISC OS as the four disc drives ADFS:0 to ADFS:3. On Linux they are accessible as TODO.

Some platforms provide extra support for using floppy discs:

Unix/XWindows

Whilst the control pane window has the focus, pressing 0, 1, 2 or 3 will eject/insert floppy disc images, those images still have to be named as above, but with moving of images around you should be able to change discs at run time.

Mac OS X

TODO Mention the GUI method of selecting disc images.

Amiga

A menu to change the disc in drive 0 can be called up with the LAmiga key

Using HD images

ArcEm supports up to four Harddiscs, hard disc images are binary files that represent a hard drive's contents. ArcEm support the ST506 disc interface from Archimedes computers allowing it to support drives up to 64MB in size. Hard drive images should be placed in the current working directory of ArcEm and be named:

You also need to specify the hard drive "shape" in the arcemrc config file. The "shape" lists the number of Heads, Cylinders, Sectors and the Record Size, these four numbers multiplied together are equal to the size in bytes of the hard drive image.

When emulating RISC OS, you will also need to use the !Configure application to set the number of hard drives within the OS.

Commandline options

ArcEm supports commandline options under Unix/X Windows and other platforms. The Amiga version will also accept them as tooltypes.

OptionMeaningAllowed valuesDefault Value
--helpDisplay list of available options and exit
--versionDisplay version number and exit
--rom <value>Specify the name of a romimage other than ROMPath from place of execution to ROM imageROM
--extnromdir <value>Specify the directory to use as the extnrom directoryPath from place of execution for extnrom dirextnrom/
--hostfsdir <value>Specify the directory to use as the base of hostfsPath from place of execution to base of hostfshostfs/
--memory <value>Change the amount of memory the emulated machine has256K 512K 1M 2M 4M 8M 12M 16M4M
--processorChange the emulated machine's processorARM2 ARM3 ARM250ARM250

arcemrc file

The arcemrc files stores information about the number and 'shape' of harddisc's attached to the emulated machine. Here is an example arcemrc:

MFM disc
1 1024 8 32 256
MFM disc
2 612 4 32 256

The five numbers represent the following:

  1. Hard drive number: 0 to 3 inclusive.
  2. Number of Cylinders: 1 to 1024 inclusive.
  3. Number of Heads: 1 to 256 inclusive.
  4. Number of Sectors per track: 1 to 256 inclusive.
  5. Sector Length: 256, 512, 1024, 2048, or 4096.

For the premade hard drive images available on the website the shape information should be available. For your own harddiscs that you have imaged you should check the Harddrive itself, as the number of cylinders, sectors and heads is normally printed on it.

RISC OS emulation

This section details functionality that is only relevant when ArcEm is running RISC OS, it does not apply for ARM Linux.

HostFS

Make sure the files hostfs,ffa, hostfsfiler,ffa and support,ffa are copied or 'sym-linked' from their support_modules sub directories into the 'extnrom' directory.

Create a directory called 'hostfs' in your executable directory, if it does not exist already. This directory is the root of the 'virtual harddisc'. (You can override this directory and put it in a different place with a commandline option).

When you boot up RISC OS 3.1x there should be a HostFS icon in the bottom left of the screen, clicking this will open up the host filing system and behaves in the same manner as a real Archimedes harddisc.

Simply copy files on your host into the hostfs directory and they will be available to RISC OS.

For non-RISC OS hosts:

Known Issues:

Mouse Scrollwheel support

Make sure the file scrollwheel,ffa is copied or 'symlinked' from the 'support_modules/scrollwheel' directory into the 'extnrom' directory.

Spinning the scrollwheel up and down in RISC OS over windows that are vertically scrollable works in the way you'd expect.

Known Issues:

Additional Screen modes

Make sure the file ArcemModes,ffa is copied or 'symlinked' from the 'support_modules/modes' directory into the 'extnrom' directory.

Once the module is loaded these modes can be chosen in the normal RISC OS way, by typing:

*wimpmode <number>

Here's a list of provided modes

Mode NumberXYcolours
32800600256
10010247682
10110247684
102102476816
104128010162
105128010164
10811528642
10911528644
112140052016
120160060016
1222403202
1232403204
12424032016
125240320256

Known Issues:

ArcEmSupport module

Make sure the file support,ffa is copied or 'symlinked' from the 'support_modules/support' directory into the 'extnrom' directory.

The ArcEmSupport module is a simple module that provides the *command ArcEm_Shutdown that allows the emulator to kill itself and return to the host OS. This *command is also available via the SWI ArcEm_Shutdown (&56AC0).

RISC OS specific usage

Commandline options

In addition to the main command line options listed above, the RISC OS version supports the following additional options:

OptionMeaningAllowed valuesDefault Value
--display <value>Select the display driver to use on startup. 'pal' selects the palettised display driver, which uses the least amount of memory and provides the best performance. However it doesn't support the use of mid-frame palette swaps (as used by games such as Lotus II & Lemmings 2). For these games it's recommended you use the 'std' driverpal, stdpal
--rbswapSwap red & blue in 16bpp mode (e.g. for Iyonix with GeForce FX)
--nolowcolourPrevent ArcEm from trying to use 1/2/4bpp modes. Recommended for Iyonix users with Aemulor running (it's quicker for ArcEm to use an 8bpp mode directly than to go via Aemulor's low-colour emulation)
--noaspectDisable aspect ratio correction
--noupscaleDisable upscaling. Recommended for best performance.
--minres <x> <y>Specifiy minimum screen resolution to use. Any modes with a resolution lower than this won't be used by ArcEm. Use this to filter out any low-res modes (e.g. 320x256) which have entries in your MDF but don't really work properly with your monitor.
--lcdres <x> <y>Specify the native resolution of your monitor. If specified, ArcEm will only ever use screen modes that will scale perfectly to fit your monitor, so you won't have ugly LCD scaling artifacts.
--menukeys <a> <b>Specify the key numbers of the two keys used to access the tweak menu. These are "low-level internal key numbers" - for a reference, see the ROOL wiki.0-255104 105 (Left & right Windows keys)

Tweak menu

The tweak menu can be accessed by simultaneously pressing both Windows keys on the keyboard. This menu allows you to change the following options:

To resume the emulator from the tweak menu, press 'R'. To quit the emulator, press 'Q'.

The --menukeys command line option can be used to change which keys are used to open the menu (e.g. if your keyboard doesn't have both Windows keys).

Performance options

As mentioned above, there are several options available in the tweak menu to help boost the performance of the display driver. These options are:

"Display auto UpdateFlags"

Setting this to "On" will boost the performance of many games. However it may not work properly with some games/software (screen updates may be somewhat irratic), so by default it's set to "Off".

"Display uses UpdateFlags", "Display frameskip"

If the "auto UpdateFlags" option is on, these options will be set and adjusted automatically by the emulator, and must be left alone.

If the "auto UpdateFlags" option is off, you can set these values manually to fine-tune performance. Briefly, the UpdateFlags option controls whether ArcEm redraws the entire screen or only the changed areas. Turning it on selects the latter, but causes some memory writes to have a significant performance overhead, since ArcEm must track all writes to screen memory. In games which make use of multiple screen banks, it's usually best to turn this option off, as it will avoid the unnecessary performance penalty of tracking memory writes (since the entire screen will have to be redrawn each time the game switches screen banks). However if the option is off the correct frameskip value must be set otherwise you won't see any performance benefits.

The frameskip option behaves slightly differently depending on whether the UpdateFlags option is on or off. If the UpdateFlags option is on, the frameskip value acts like the frameskip value you'd find in any other emulator. A value of 0 causes the screen to be updated every frame; 1 causes it to be updated every 2nd frame, etc. E.g. if you're in a 50Hz screen mode, and a game is running at 25fps, a frameskip value of 1 will give you a slight performance boost without hurting framerate. Values of 2 or more will give greater performance boosts, but will result in the screen being redrawn less often.

If the UpdateFlags option is off, then there are generally two situations in which the screen will be redrawn: when the running game switches to a different screen bank, or when the frameskip counter runs down. Assuming the game keeps running and keeps swapping screen banks, the frame skip counter is irrelevant, as it will never run down. However if the game stops running, or switches to a mode where it doesn't use multiple screen banks (e.g. in menu screens) the screen will stop being redrawn. This is where the frameskip counter becomes important. If you're in a 50Hz mode, and the game is running at 25fps, a frameskip counter of 2 would likely be the most appropriate. This means that ArcEm will only force the screen to be redrawn if the framerate drops to below 17fps.

X11 specific usage

Environment options

In addition to the main command line options listed above, the X11 version may be tuned using the following environment variables:

OptionMeaningValue
ARCEMXSYNCUse Synchronous X protocolEnabled when defined
ARCEMNOWARPDon't attempt to use XWarpPointerEnabled when defined
ARCEMXMOUSEKEYChange key used to claim mouse pointerDefault is Keypad + when not defined. Other values from X11/keysymdef.h

Known Issues and bugs

All platforms

Unix/X Windows

Microsoft Windows

Mac OS X

RISC OS

Amiga