Development version (CVS HEAD) Manual http://arcem.sf.net/
This user manual is for the latest version of ArcEm, only available from CVS.
TODO
TODO
TODO
TODO
Follow the instructions appropriate for your system:
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.
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.
TODO
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.
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.
Follow the instructions appropriate for your system:
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
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.
TODO
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.
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.
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:
From a shell prompt:
$ cat ROM1 ROM2 ROM3 ROM4 > ROM
From a cmd.exe command prompt:
copy /b ROM1+ROM2+ROM3+ROM4 ROM
TODO
From the command line:
*print ROM1 { > ROM }
*print ROM2 { >> ROM }
*print ROM3 { >> ROM }
*print ROM4 { >> ROM }
From the commandline
join ROM1 ROM2 ROM3 ROM4 as ROM
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.
Some of the platforms require specific instructions to let you move the mouse around.
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.
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.
TODO
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.
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.
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:
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.
TODO Mention the GUI method of selecting disc images.
A menu to change the disc in drive 0 can be called up with the LAmiga key
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.
ArcEm supports commandline options under Unix/X Windows and other platforms. The Amiga version will also accept them as tooltypes.
| Option | Meaning | Allowed values | Default Value |
|---|---|---|---|
| --help | Display list of available options and exit | ||
| --version | Display version number and exit | ||
| --rom <value> | Specify the name of a romimage other than ROM | Path from place of execution to ROM image | ROM |
| --extnromdir <value> | Specify the directory to use as the extnrom directory | Path from place of execution for extnrom dir | extnrom/ |
| --hostfsdir <value> | Specify the directory to use as the base of hostfs | Path from place of execution to base of hostfs | hostfs/ |
| --memory <value> | Change the amount of memory the emulated machine has | 256K 512K 1M 2M 4M 8M 12M 16M | 4M |
| --processor | Change the emulated machine's processor | ARM2 ARM3 ARM250 | ARM250 |
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:
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.
This section details functionality that is only relevant when ArcEm is running RISC OS, it does not apply for ARM Linux.
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:
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:
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 Number | X | Y | colours |
|---|---|---|---|
| 32 | 800 | 600 | 256 |
| 100 | 1024 | 768 | 2 |
| 101 | 1024 | 768 | 4 |
| 102 | 1024 | 768 | 16 |
| 104 | 1280 | 1016 | 2 |
| 105 | 1280 | 1016 | 4 |
| 108 | 1152 | 864 | 2 |
| 109 | 1152 | 864 | 4 |
| 112 | 1400 | 520 | 16 |
| 120 | 1600 | 600 | 16 |
| 122 | 240 | 320 | 2 |
| 123 | 240 | 320 | 4 |
| 124 | 240 | 320 | 16 |
| 125 | 240 | 320 | 256 |
Known Issues:
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).
In addition to the main command line options listed above, the RISC OS version supports the following additional options:
| Option | Meaning | Allowed values | Default 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' driver | pal, std | pal |
| --rbswap | Swap red & blue in 16bpp mode (e.g. for Iyonix with GeForce FX) | ||
| --nolowcolour | Prevent 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) | ||
| --noaspect | Disable aspect ratio correction | ||
| --noupscale | Disable 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-255 | 104 105 (Left & right Windows keys) |
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).
As mentioned above, there are several options available in the tweak menu to help boost the performance of the display driver. These options are:
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".
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.
In addition to the main command line options listed above, the X11 version may be tuned using the following environment variables:
| Option | Meaning | Value |
|---|---|---|
| ARCEMXSYNC | Use Synchronous X protocol | Enabled when defined |
| ARCEMNOWARP | Don't attempt to use XWarpPointer | Enabled when defined |
| ARCEMXMOUSEKEY | Change key used to claim mouse pointer | Default is Keypad + when not defined. Other values from X11/keysymdef.h |