Aemulor logo

Software version 2.55

Introduction

Aemulor allows you to run old 26-bit applications and modules (written before the days of 32-bit RISC OS) on the following machines/targets:

Please note that some of the functionality available in the IYONIX pc build of Aemulor is not available on the other machines, either because it cannot be implemented in the original manner, or because an alternative approach is now more appropriate.

26-bit code cannot be executed directly by the XScale, ARM9 and Cortex processors used in these machines, nor on RISC OS 5 on any target, because the old 26-bit addressing modes are not present/supported.

ARM History: The distinction between '26-bit' and '32-bit' refers to the address space used for instruction addresses. In the ARM2 and ARM3 processors the program counter held 24 bits, and since instructions were always 4 bytes long, this meant that the address space was 64MiB (2 raised to the power of 26 bytes). The data width of the CPU was always 32 bits.

Licensing

The base functionality of Aemulor is provided as free software with no warranty or guarantee of fitness for purpose, and thus no liability. It is no longer commercial and does not require a licence for operation.

From version 2.54, Aemulor includes some of the licence management code that Sendiri uses for its commercial software, and Sendiri may in future release additional functionality such as new features, performance improvements or additional compatibility, for a nominal fee using this licensing scheme.

When Aemulor or other Sendiri software is downloaded from Sendiri Store, the archive includes a Licences file which maybe dragged into the Licences window that is viewable from the 'Licence...' option in the iconbar menu of the user interface.

For clarity, although the software is free to download and use, it is not permissible to distribute Aemulor without explicit permission from Sendiri, since the software remains subject to copyright.

Installation

Aemulor is supplied as an archive/zipfile containing a single RISC OS module that can either be loaded manually by double-clicking on the module, or be installed in the machine's boot sequence so that it starts automatically. Since it is necessary for Aemulor to modify the memory map, which in turn restricts the amount of memory available for use by some 32-bit software, it is nowadays recommended that Aemulor be started and stopped manually only when required to run legacy 26-bit applications.

If you wish to run 26-bit code automatically on startup, eg. to have a 26-bit application launch itself every time you switch on the computer, then you will have to install Aemulor in the boot sequence. (Also, some applications may require Aemulor to be started before the desktop starts up.) To do this, simply copy the Aemulor module from the archive into the directory !Boot.Choices.Boot.PreDesk and then restart your machine.

Note: some people have reported that on a few machines, they've had to rename the Aemulor module in PreDesk so that it's called !!!Aemulor, causing it to be loaded sooner. This shouldn't really be necessary, but it may be worth trying if you have problems.

Program information window

The !Aemulor application, accessible via Apps on the icon bar once the Aemulor module is running, provides an interface that allows you to configure the emulator and to see what code is being run under emulation. If you want to close the user interface without stopping the emulator, so that 26-bit code will continue to run, just use the choose 'Quit -> Front end' on its iconbar menu.

Choosing 'Emulator too' on the Quit submenu will stop the emulator as well, thus also closing all 26-bit applications and modules. In this case you will be warned if code is still running under emulation, or if one or more 32-bit modules have been loaded under emulation and may still be in use by 32-bit software. This happens with some versions of the Impression Style application.

Configuration


Configuration window

This window allows you to configure the way that Aemulor behaves. Aemulor stores its configuration settings in Choices:Aemulor in the conventional manner. (So on a normal machine they can be found in $.!Boot.Choices.Aemulor)

Starting applications

This option allows you to choose whether Aemulor should automatically detect and intercept all attempts to run 26-bit code (eg. double-clicking on old applications or modules). If you choose this option Aemulor will work entirely transparently, as if the 26-bit applications were running normally; and you can even close the Aemulor user interface by choosing Quit on the menu.

There are some limitations, however, because it isn't always possible to tell whether code needs to be emulated or not, ie. whether it's old 26-bit code. In these cases we have taken the decision that it is important for Aemulor not to interfere with the normal operation of 32-bit applications, so Aemulor will only run something automatically if it is definitely 26-bit code.

If you choose to "Run all 26-bit code automatically" and find that a 26-bit application does not work properly, you can drag the application's icon from the Filer and into Aemulor's "Applications" window to tell Aemulor that any 'ambiguous' code found within that application directory is to be treated as 26-bit code. Programs that can't be run automatically are usually fairly complex applications using a number of modules, and often report that they need "version x.yz of module A" if you try to run them without telling Aemulor that they are 26-bit code.

Just in case there is a problem with Aemulor that causes it to interfere with 32-bit applications running natively, there is an alternative option of only emulating applications that are manually dragged onto Aemulor's icon on the icon bar. If you encounter such problems please contact us and we will try to investigate and fix them so that Aemulor's operation is once again transparent.

Please note that if your boot sequence includes 26-bit code then you should choose the 'run all 26-bit code automatically' option because otherwise the 26-bit code will not be run under emulation and errors will occur when the machine boots.

Fault logging

Ordinarily you should choose 'Do not produce a log file' in the Config window, because applications could contain bugs that would cause Aemulor to produce a fault report, wasting space on your hard drive.

If, however, you report a suspected fault/incompatibility of Aemulor to us then we may ask you to change this option temporarily and send us the resulting log file(s) to help us study and correct the problem.

Please bear in mind that applications which fail on a RiscPC running RISC OS 4 will probably fail in the same way under Aemulor. However, if you find that your application is failing in a different way or more frequently, then this may be due to a limitation of, or fault within, the emulator. So please report the problem to us at the address given below so that we can improve Aemulor for the benefit of other users.

Memory restrictions

In its original incarnation the use of Aemulor restricted all running applications to no more than 26MiB of application memory apiece, in order to ensure that the memory map closely modelled that of RISC OS 4 for maximal compatibility. This restriction affects all 32-bit applications also for the time that Aemulor is running.

Since Aemulor is now used primarily for desktop applications, which tend to rely more upon formal APIs and are less likely to access hardware and specific memory regions directly at assumed addresses, there is now the option of an alternative memory map which permits up to 52MiB to be allocated to each application.

The configuration window allows you to choose whether Aemulor uses the original memory model, for maximum compatibility, or the altered memory model that makes more memory available to 32-bit software that requires it, but please note that this setting only takes effect when Aemulor is restarted.

Dynamic areas

Some applications such as StrongED 4.64 and Schema 2 do not work properly if their dynamic areas are allocated at high addresses. This can occur even on RISC OS 4 but with the altered memory map of RISC OS 5 and the larger amount of RAM fitted to the IYONIX pc it is much more likely now. Aemulor can therefore provide dynamic areas at low memory addresses for applications that require this. The Applications window allows you to specify which applications should use this low memory area, but it should be noted that the area is of finite size (448MB) so the Config window allows the size of individual areas to be restricted. If you specify a maximum size of 0 then no limit is imposed.

Hiding the Aemulor icon

Aemulor is designed to operate transparently, so once you've told Aemulor which of your applications are 26-bit (by dragging them into the Applications window), you probably won't need to use the user interface very often. By un-ticking the 'Display the Aemulor icon after booting' and clicking on 'Set' you can save some space on your icon bar. (Obviously you should only do this if you've also told Aemulor to run 26-bit code automatically.) The user interface can still be accessed via the 'Apps' icon on the icon bar.

Note that this option only applies when Aemulor starts up during the machine's boot sequence. If you start Aemulor manually by double-clicking on the module, the icon is always displayed ready for use.

Applications window

Applications window

If Aemulor is unable to recognise an application as 26-bit code, as described above, then you can drag that application into Aemulor's 'Applications' window to tell Aemulor that it should be treated as 26-bit code. You will then be able to start it in the normal way by double-clicking on it.

An 'Add' button is provided so that you can enter a pathname that contains wildcards. For example, *.!Schema2 means that Schema2 will be treated as 26-bit code wherever it's running from, allowing you to move the application without reconfiguring Aemulor.

Adding applications

The Applications window also serves the secondary purpose of telling Aemulor which emulation engine to use for each 26-bit program. Aemulor contains three different engines :-

  1. the StrongARM engine that uses unique hardware features of the XScale processor and thereby offers much greater performance.
  2. the ARM610 engine which will also run some older applications that are not StrongARM compatible
  3. the ARM3 engine which is much slower but will also run some pre-RiscPC software

IYONIX pc: Since the StrongARM engine is typically about 3.5 times faster than the ARM610 engine it should be tried first, and only if an application fails to run (often with an 'abort on instruction fetch' or an 'undefined instruction' error) should the ARM610 engine be used for that application.
NOTE:Unfortunately the StrongARM engine is unavailable on more recent builds of Aemulor on account of it not functioning reliably and the current unavailability of test hardware to resolve the issue.

Other machines:The StrongARM engine is currently unavailable on these machines because Aemulor has not been modified to exploit the available hardware. It may be possible to implement the StrongARM engine on these machines in a future version, though this has not yet been demonstrated.

Some very old software, especially games, won't run with the ARM610 engine because it makes heavy use of self-modifying code, a practice which is frowned upon nowadays. For these programs it's worth trying the ARM3 engine which offers the best compatibility with old code at the expense of much speed.

The ARM3 engine can also be useful for old games which expect to be running on slow hardware and are therefore too fast to be playable when emulated using the StrongARM and/or ARM610 engines.

When an application is started, Aemulor reads downwards in the applications window trying to match the application's filename against each of the entries in this window. Entries may contain wildcards, eg. *.!Style will match any copy of Impression Style, wherever it may be located on the system.

At the bottom of the Applications window is an entry "All other applications" which will be used for any 26-bit programs that don't match any of the earlier entries. By selecting this entry and clicking on 'Edit' you can choose the default emulation engine. This should normally be left as the StrongARM engine, but if for some reason you have a lot of old programs then you may wish to change it.

Aemulor also allows you to specify, for each application, whether dynamic areas should be created at low addresses. As noted earlier, some 26-bit applications cannot cope with the areas being allocated at high addresses, but since the size of the low memory is only 448MiB, only those apps which are known to fail otherwise should have the "Use low addresses for dynamic areas" option ticked.

All changes in the Applications window take effect immediately and are automatically remembered. There is no need to tell Aemulor that the changes must be saved.

To help you find a particular application in the Applications window, Aemulor provides a 'Find' dialogue, which can be opened by pressing F4 when the Applications window has focus. You can then type in the application name (without the '!') or just the first few characters to quickly skip to the appropriate line in the window:

Finding applications

Also included are buttons to skip to the next and previous matches and the ability to specify case-sensitive or insensitive matching. Press Escape to close the window or click on the close icon.

Lastly, as a convenience, the Applications window provides two further buttons 'Run' and 'View' which mimic the corresponding buttons in the Filer's Find window, ie. they start an application and open the directory containing an application, respectively.

Modules window


Aemulor provides support for loading and using 26-bit modules within 26-bit applications. This is necessary because 32-bit versions of RISC OS do not support 26-bit modules.

The modules window shows you which 26-bit modules are currently loaded under Aemulor, their version numbers and locations as a graphical equivalent of the *Modules command provided by the OS. This window also serves as a handy way to load 26-bit (or 32-bit) modules by dragging them into the window. If a 32-bit module is loaded in this way then any 26-bit equivalent that is already loaded will be killed first.

The modules window can also be used to kill one or more of the loaded 26-bit modules. Aemulor will warn you if the module is being used by one or more 26-bit applications; if it is, be sure that you know what you're doing, because killing the module could cause failures or loss of work.

A command called *Modules26 allows you to view the 26-bit modules from a command line prompt, and the optional *Modules26 -all parameter shows you the modules that are visible to 26-bit applications, ie. all of the 32-bit modules that are backwards-compatible and can be used by 26-bit code, and the 26-bit modules that are currently loaded under Aemulor.

Once you have run Aemulor you will find a directory called Modules located inside !Boot.Choices.Aemulor into which you can place any 26-bit modules that you wish to be loaded automatically when Aemulor starts up. This facility is useful when a 32-bit module is found to be not backwards-compatible; the older 26-bit version can be copied into the Modules directory and will thus 'hide' the 32-bit version from any 26-bit code wishing to use that module - the 26-bit version will be run under emulation instead.

Tasks display

The Tasks display window shows you the applications that are currently running under emulation, and the emulation engine(s) being used. Additionally you can see how much memory Aemulor is using to emulate each application.

Clicking the Menu button over on an application will select it and display a menu that allows you to get further information or to quit that application.

Also shown are the dynamic areas that are being emulated by Aemulor, ie. those which were created in the 'low memory area'. (See application options.)

Clicking the Menu button over a dynamic area allows you to delete that area which can be useful if a task has terminated abruptly and left its dynamic area behind. Be careful not to delete areas that are still being used by an application because doing so will almost certainly cause it to fail.

Filetypes

Aemulor allows two special filetypes to be used to also indicate that an application should be run under emulation.

 Basic26 (&F7A)

To indicate that a BASIC program contains 26-bit assembly code, and should be run under Aemulor, set the filetype to BASIC26

 Obey26 (&F7B)

This is designed for allow an application (regardless of language) to be run under Aemulor by changing its !Run file to filetype OBEY26.

For both of these filetypes, if you want the application to no longer be run under Aemulor, just change the filetype back to BASIC or OBEY.

Using Aemulor from the command line

If you need to run a 26-bit application from a command line and Aemulor isn't automatically detecting that the application needs to be emulated, you can prefix the command with AemuExecute to force it to be emulated.

This is, in fact, how the 26-bit filetypes Obey26 and BASIC26 are implemented and it can be used to ensure that other files are executed under emulation. For normal desktop applications this isn't necessary because double-clicking a document file causes the application to be started and Aemulor already knows that the application is 26-bit code.

AemuExecute should work for any *command, including module commands - eg. you can 'enter the 26-bit world' by typing "AemuExecute BASIC" within a TaskWindow, and then any commands/programs that you run using the BASIC interpreter are 'emulated' by Aemulor so that they behave the same as they do on RISC OS 4.

Be warned that if you use AemuExecute to run code that is already 32-bit compatible then it will also run under emulation, and will therefore suffer a performance hit; since such code is 26/32-bit neutral and will run either under Aemulor or natively.

Help on 26-bit modules and their commands is available from the command line (32-bit or 26-bit) by typing *Help as normal. Note that Aemulor will match your query against the 26-bit modules first and then let RISC OS check the 32-bit ones. If RISC OS finds no matches it will display No Help found even if Aemulor has already displayed some 26-bit help text.

Aemulor TaskWindow

For convenience when calling 26-bit command-line utilities, Aemulor provides a TaskWindow via its icon bar menu. Choosing this option will open a 26-bit TaskWindow and everything executed within this window will run under Aemulor including *commands and, after typing 'BASIC' to invoke the BASIC interpreter, any BASIC commands or programs that you enter.

Aemulor and Screen Modes (IYONIX pc only)

Aemulor is able to emulate in software the low-colour screen modes that are not available natively on the IYONIX pc, namely 2-,4- and 16-colour modes. It does not, however, provide new screen resolutions and frame rates at present, so any screen modes required by games that you want to run must be included in your Monitor Definition File (MDF).

The MDF for your monitor can usually be found in $.!Boot.Resources.Configure.Monitors... and it will be necessary to edit this to include new mode definitions. A sample MDF containing many useful screen modes is supplied in the Support directory.

Emulated modes (IYONIX pc only)

The emulated low-colour screen must be converted to the native 256-colour screen by Aemulor. Although this operation must be performed in software, it incurs a fairly minimal performance hit, by translating the pixel writes as they occur rather than repeatedly converting the entire screen in software. Although this feature is intended for use with old educational software and games, it will also work in the desktop.

Games under Aemulor

Aemulor is able to run a large number of the games that have been published for the Acorn Archimedes and RiscPC machines over the years. Since games are a much more demanding use of Aemulor than desktop applications, here are a few hints and tips that may help to get old games working:

  1. Change the processor type (StrongARM/ARM610/ARM3) for that game. Some games will only work on certain processors; as a rough guide the game's age should be a clue:

    • 1987-1994 = ARM3 Archimedes
    • 1994-1996 = ARM610 RiscPC
    • 1996- = StrongARM RiscPC

    It can also be helpful to use an older processor type if you find that a game is too fast under Aemulor.

  2. Many games require specific screen modes which are not normally provided on more recent machines. Often one or more screen mode definitions (called 'MDF' or 'Modes') can be found inside the application itself and these should be copied into the Monitor Definition File (MDF) that you use for your monitor. (Inside $.!Boot.Resources.Configure.Monitors..)

    It's worth checking the game's !Help file, if it has one, for further instructions.

    After modifying the file, you should double-click on '!Boot' and then 'Screen' to open the Screen Configuration utility. This provides an easy way to test the new screen mode on your monitor to make sure that it displays correctly.

  3. A related problem is that often the frame rate of the native screen mode is much higher than the game expects, causing the music and/or game itself to play too quickly. This problem is compounded by the fact tha RISC OS will normally choose the highest frame rate available for a given resolution.

    You may find that you have to comment out/remove high frame rate, low-resolution modes. A future release of Aemulor will aim to make the use of non-native screen resolutions and frame rates a lot simpler.

  4. Spheres Of Chaos performs a lot better if the Vision option 'Draw to buffer' is used rather than 'Draw directly to screen.' Other games may benefit from similar settings where available.

  5. Some games assume that they can write directly to low memory addresses (particularly &4000-&7FFF). These addresses are protected on RISC OS 5 and it is necessary to run a small patch that removes this protection before the game will run. The 'Unprotect' patch is include in the Support directory and can be copied into the game's application directory. The following command should then be inserted at the start of the game's !Run file:
    Run <Obey$Dir>.Unprotect

Technical Details and Limitations

Lastly...

Aemulor is a private, non-commercial product that is made available and supported for the benefit of all RISC OS users, but it still takes time to develop and maintain. If you would like to help support its development you may
Buy Me a Coffee or
Donate via PayPal.

Please report any problems relating to numbered releases to the email address below:

Sendiri Store: https://sendiri.co.uk/store
Website: https://sendiri.co.uk/aemulor
Email: support@sendiri.co.uk

Copyright (C) Adrian Lees, 2002-2022