Software version 2.20
Manual version 1.00
Introduction
Aemulor allows you to run old 26-bit applications and modules (written before
the days of RISC OS 5) on the IYONIX pc. 26-bit code cannot be executed
directly by the XScale processor used in the IYONIX pc because the processor
does not support the old 26-bit addressing modes.
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 Iyonix's
boot sequence so that it starts automatically. The archive also contains a ReadMe
detailing the latest information about the release not included in this manual.
To extract the software from the file you download from Aemulor.com, set the
filetype of the resulting module to &DDC or "Archive", then double click on
it. A read-only SparkFS is included with the IYONIX pc so you do not need any
additional software to install Aemulor.
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 Iyonix, 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.
This shouldn't really be necessary, but it may be worth trying if you
have problems.
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 choose Quit on the icon bar menu. Choosing
'Emulator too' on the Quit submenu will stop the emulator as well, thus also
closing all 26-bit applications and modules.
Config 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
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.
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.
Fault logging
Ordinarily you should choose 'Do not produce a log file' when a fault occurs,
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.
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.
Modules window
Aemulor provides support for loading and using 26-bit modules within 26-bit
applications. This is necessary because RISC OS 5, being a fully 32-bit OS,
does 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.
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.
The Applications window also serves the secondary purpose of telling Aemulor which
emulation engine to use for each 26-bit program. Aemulor contains two different
engines :-
- the StrongARM engine that uses unique hardware features of the XScale processor and thereby offers much greater performance.
- the ARM610 engine which will also run some older applications that are not StrongARM compatible
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.
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 448MB, 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.
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.
