Setup instructions for !ArchiEmu

!ArchiEmu emulates (currently) an Archimedes 310, with memory from 0.5 Mb up to 16 Mb, 2 harddiscs and 4 floppy drives. It can emulate Arm2,Arm3 with Arthur 0.3,Arthur 1.20, Riscos 2/2.01 or Riscos 3.00/3.10/3.11/3.19/3.20. The host computer should also be a Riscos computer, such as RiscPC (with StrongArm processor), Iyonix, A9home, Beagleboard, RaspberryPi. On even more new computers like Titanium it should run but I have not tried this. RISCOSonLinux should also be OK - tested this on RPI3B+ with UbuntuMate 18.04 and Raspbian Buster and RPI 4 with RaspberryPi OS and Ubuntu 32-bit.
It's a development of !A310Emu; I got stuck with !A310Emu when it became clear that (especially games) require tricks that were not compatible with the way A310Emu was organised. And I found a faster emulation method.  It's still in development, it may harbor the occasional bug. Singletasking is still provisional.
Known bug: In singletasking mode, the emulator needs to remove the limits between which the mouse can operate (eg. for singletasking mouse-operated games). For A9home compatibility, and for some advantages in program structure, the emulator itself remains multitasking and so continues to call Wimp_Poll. As the WindowManager does not like mousepositions outside the Wimp background (ie. it crashes the next application with a zeropage error and an unaligned memory access) this had to be circumvented by bringing the pointer to the center of the screen everytime, but there is an inaccuracy resulting in the pointer drifting to one side, sometimes.
Known bug: Singletasking still far from optimal
Known bug: EmuTrsf cannot drag selections of files from one instantiation to another.
Etc.
Riscos 3.20 is a project on www.stardot.org.uk where Jon Abbott (of ADFFS fame) has prepared a new, 4M rom for the Archimedes computer; it was not too difficult to adapt archiemu for this ROM. The disc light however flashes when starting up - problems with ROM crc. When flashing is over the click on the disclight of 'floppydrive' 0 and you see what this code means. I used a recent Harddisc4 image, transfered with EmuTrsf to a standard harddisc imagefile. 

PREPARATION
--------------

Memory requirements on your host computer (RiscPC/A9home/Iyonix/Beagleboard(xM)/RaspberryPi): depends on the amount of RAM you want to use in the emulator (0.5-16 Mb), plus the size of the 'instruction buffer'(up to 2 Mb), the OS (0.5-2Mb), the program itself, space for floppydisk images (up to 6 Mb), the program itself and its workspace (2Mb). So anywhere between 5 and 32 Mb.

Pandaboard, A7000, Kinetic, Microdigital Omega should work but I have not tested this.

Free space on your harddisc: ArchiEmu uses filecore images as its harddiscs up to 512Mb each. (But 'harddiscs' are optional, if you don't configure harddiscs they are not needed). Two files between, let's say, 20 Mb - 500 Mb, for which you will have to find space. And you will want to collect some floppydisc-images. So the required space on your harddisc mainly depends on the size of the harddisc images you want to use; including the ADF-floppydisc images  let's say, 1 Gb.
Unpack !ArchiEmu from the Archi.zip archive; you need SparkFS or SparkPlug for this. Drag the !ArchiEmu icon to anywhere on your harddisc (or the thing that substitutes your harddisc such as an SD-card or an USB-stick)

The setup/use of the system has changed as of recently, because the possibility is added to use freestanding directories with the configuration and harddiscs etc for various separate setups, and keep the actual emulator out of sight. This distro should contain the actual emulator, !ArchiEmu, along with a couple of demo directories. It's recommended to use the emulator with these 'game directories', but you can also use the emulator on its own. Gamedirectory is something in search of a better name, it is a directory with some files, at least a Run file and a Config file, and maybe a !Sprites file and floppie/harddisc images. They start up the emulator from a distance. They can be used with games, applications on the harddis(s), etc.
What is the advantage? You could have various setups all with their own !Runimage, !Templates and config file, of course, but when bugfixes are available you would have to upgrade them all. With the old system, when you want to run a program that's only available for one type of OS. you first would have to change the setup, and change it back when you quit the program. Some games don't run well at higher emulation rates, or your host machine prefers frames to be skipped etc so it would be nice to have the setup of the emulator with the game. Gamedirectories allow this. The idea is to let !Game.!Run start the !Config file that contains everything including the names of floppies, harddiscs, cmos, and make !ArchiEmu active as soon as it recognises the filetype of !Config, read in the configuration, start up, load the floppie , run the game.
When you use ArchiEmu with game directories, place !ArchiEmu somewhere so that it is 'seen' as soon as your computer starts up, e.g. !Boot.!Resources. The game directories can be anywhere. !ArchiEmu still can be used in the 'old' way. Gamedirectories may also carry the name !ArchiEmu.
The ArchiEmu directory and the 'game directories' differ in their contents. The first has the Runimages, operating systems, helper modules, templatefile; the latter a configuration file and one or more floppies and/or harddiscs and maybe Cmos files.

First, the ArchiEmu directory and how to use the menus etc.
!ArchiEmu in its present form is in Distribution.!Boot.Resources.
Open the !ArchiEmu directory (by pressing Shift key and clicking on the ArchiEmu icon at the same time). You should see a number of files:
!Boot: a line to add the !Sprites file to the spritepool of your system, and a line to associate a filetype (FileCore=&FCD) to the emulator.
Config: file should miss, so that your old Config file will be preserved when upgrading. Config files can be created in the Setup window, or created/saved automatically under certain circumstances. Note that Config was called !Config previously, maybe you have to rename your old !Config file. The files are backward compatible as more options get added. If you only use game directories this !ArchiEmu directory (with the !runimage executable) can do without a Config file.
!Run: ensures that a few modules are there, especially RBMemMgr and SharedSound. RBMemGr is supplied by MemMgrMod inside the RMStore directory; SharedSound is part of Riscos 4/6 (RiscOS Ltd) and Riscos 5 from ROOL. ArchiEmu's requirements from SharedSound are modest so I presume that earlier versions than 0.58 (=inside Riscos 4.02) will work too, but I have not tested this. Atm SharedSound is excluded from the RISCOS rom supplied with RISCOS_on_Linux, archiemu disables sound if it does not find SharedSound. There is (in Distrib::!Boot.Resources.!Archiemu.!Run) a line that is outcommented, '|RMEnsure SharedSound..' if the RISCOSonLinux development will add sound this '|' can optionally be removed; ArchiEmu will notice the presence itself automatically.
!RunImage is the uncompressed version, !RunImage' is compressed so it's a bit faster (twice for BASIC code, assemblerspeed unaffected) and smaller; if RAM space in your host computer is a precious commodity you could use !RunImage' (change the !Run file for this) and set the wimpslot 700Kb less, it's in the line 'WimpSlot -min2300K -max 2300K' in the !Run file. !RunImage' was compressed with !RegGraph editor. (Menu on Main-->utilities-->Crunch). 
CMOS can be there; is an empty directory, but will get filled with cmos files once you use and reconfigure things in the emulation. These files are copies of the CMOS contents of the Archimedes. They are very different from the Config file that the emulator itself uses to set up things. CMOSRAM was the name of a small chip inside the Archimedes computer, that used to store various settings such as the number of floppydiscs and harddiscs etc, and these values were remembered thanks to a battery that kept the data alive while the Archimedes power was off. As this program has no battery we must store those settings somewhere else, ie. in a file. 
OS directory is (=might be) empty, it should contain at least one operatingsystem image, otherwise the emulator will not start up. 
There are several methods to get these OS-images; for now a few of them are supplied (1) but you can also get them from an existing Riscos2/3 computer (2) and the best method (3) is to buy the OS-files from RiscOS Ltd. They offer a CD with legacy OS files and a huge amount of related software for virtually no money at all. The address is:http://www.riscos.com/shop/ . Please note that the Riscos Rom files on this CD do not have the names that ArchiEmu expects, so copy over ROM120,ROM200 or ROM310 to the ArchiEmu.OS directory.
The names of the OS'es do not matter anymore, the program examines each file inside the OS subdirectory and classifies them using the information about the OS in that file. (a text 'MOS Utilities' with a version number following; the emulator is tested with 0,30,1,20,2.00,2.01,3.00,3.11 and 3.19). But if your OS is supplied in 4 parts, ic24 ic25 ic26 and ic27 typically, you should join these 4 files in one big file. So start up an editor, load ic24 first, at the end of this file add ic25, then ic26 and last ic27, save them all as one big file.
Option 3 (ordering from RiscsOS Ltd) has the huge advantage that you get a lot of extra software with your OS-files. For instance there's the Riscos3 Userguide in the Riscos 3.70 section.
Make sure the OS-files end up in the OS-directory of the emulator application (!ArchiEmu.OS)
(For the current emulation the names Riscos 3.10 and Riscos 3.11 can be interchanged. The naming of the OS-es in the emulator must be improved). For the emulator the filetypes don't matter.

STARTING UP
---------------
You can now start up the emulator itself, or start it up via one of the demo/games directories. 
The demo/games directories come with some configuration ready, the emulator itself can be relocated from its default place (!Boot.Resources) to somewhere you like it to be. The emulator itself does not have a Config file and harddiscs; for use with demo/game directories that is unnecessary. But if you use !ArchiEmu directly you have do do some configuration: click on the !ArchiEmu icon. This causes the emulator to start up. It probably complains that it cannot find a configuration and opens the Setup window. Else, press Menu on the iconbar icon, Choose Setup/Config. Or (if it complained already) you can choose between automatic setup or you can open the Setup window.

Let's suppose you choose to open Setup; setup can also be reached from iconbarmenu. A longish dialogue window is in front of you.
Choose OS version from the menu button; RAM size, processor,hostmachine,instruction predecode-buffersize. Instructionbuffersize is not important, choose anything. Hostmachine IS important. If hostmachine is chosen wrong the application can use instructions unknown to your computer and crash. 'Other' is the safe choice without specific hardware requirements, ie. no hardware floppie, no LDRD instructions etc.
Most likely there is/are no harddisc(s) yet. What is a harddisc in emulation-land?

The emulator must get the illusion that there is a harddisc, provided it's configured to have one or more harddiscs. Now, everything is emulated, so various tricks can be used to give that illusion to the emulator. There are 2 approaches. One is to use a special 'filing system' that intercepts all A310 accesses to a harddisc, and returns information coming from actual files in a special directory. This is how HostFS works with Arcem, or with VRPC/RPCEmu on non-Riscos hosts. The other approach is to use a big file, about the same size as the harddisc that's it is meant to emulate, and to read and write into that big file as if it were a real harddisc. Read/write addresses are calculated with knowledge of the track,sector and head numbers, and the size of each sector. This is how the 'harddiscs' for ArchiEmu work. Advantage of this approach is, you can always call files by a path ADFS::$.4. ... so it should be more compatible for some applications. Rogue applications only do harm on the emulated harddisc, not on your real harddisc (if the emulator is written well, that is). Disadvantage is the maximum size, 2 Gb for some host machines; but as Riscos3 only addresses up to 512 Mb this is not yet a problem.
You can drag an existing harddiscfile on the writable-icon below 'full name of harddisc4' / 'full name of harddisc5'. Or create a new harddisc: at the right of the icon under 'full name of harddisc4.. etc, there is a small rectangular icon with a picture of a menu. Click on it, this is a menu-icon. A menu will appear. You can now choose ready-made images from this menu OR choose a custom design with heads, sectors and tracks of your liking. The readymade images are formatted already but the designs with selectable #heads,#sectors,#tracks must be formatted with !Hform (a program that formats harddiscs) once you started up the emulator, inside the window of !ArchiEmu.  !Hform is on one of the Riscos3 floppies. By all means do NOT reformat the harddisc of your host computer. Format with !Hform INSIDE the emulator. Compared with the ready-made images/harddiscfiles, the custom-made ones lack some data; these must be filled in with !Hform once you are inside the emulation. Note that Riscos310-ADFS understands harddrives up to 512 Mb, but !Hform can only format 256 Mb on a H63463 harddisk-controller (the one that is emulated in !ArchiEmu). 
To get rid of a harddisc without erasing it, just clear the writable field with the harddisc name in Setup window, or *rename the harddiscfile so that ArchiEmu cannot find it.

Directory of CMOS file: Drag in the directory where you want the cmos files stored, or fill in the path by typing on your keyboard, it should have 'CMOS.' at the end and it should preferably live in the game directory you just clicked. But it can be anywhere. Cmos can also go with the Config file, there is an option to choose this. Note that if cmos is included in the config file, changes only are remembered if you save the config file.

Key combination to quit singletasking: There's a menu button to the right, to choose the right descriptions. Left Alt + Copy/End is usual. On Arcem it's the two windows buttons (by default, it's also changeable there), but not every keyboard has these two, e.g. the RiscPC keyboard not at all, some minikeyboards have only one. (Btw in !Arcem keycombination is also configurable).

Max size of multitasking-window: you could try 1600 horizontal, 1200 vertical. Limits the size of the window, if you think too much time is needed to update the main window and the emulation gets too sluggish. (because a LOT of bytes must be shoved between emulated videoram of the A310 and the videomemory of your host computer). (Also a bit-per-pixel mode on your host machine equal to the one of the emulation, eg.256 colours, and a lower resolution allow faster emulation). Filling in '0' in the maximum-size-icons lets the emulator ignore this value.

Pointer shape: from emulated machine and host machine give the smoothest mousepointer movement, icon movement can be jerky but can look more natural. However some programs require pointer as an icon, for instance the Xcentric demo and designprograms where the active point of the mouse is not in the left-upper corner of the pointer.

Enable VIDC enhancer: a VIDC enhancer on 36MHz (and 25.175 MHz) is 'built-in' and a module is supplied for Riscos 3.10 and above. For Riscos2, you have to provide a vidc enhancer module on the harddisc-file. (Riscos 3.00 and less are unaware of so called 5th-column ROMs, wherein the extra modules like vidc-enhancer are supplied; if the 5th-column mechanism is activated for riscos 3.00 and less, the emulationn crashes, so it's disabled there).
To choose these enhanced screenmodes, this icon could be ticked. If you only want bigger desktops, a vidswitch module is unnecessary as you can also use ArcemModes from the Arcem distribution, which work at a lower framerate (actually so low that real monitors would have problems displaying them). But --some-- trackermodules like RiscTracker seem to keep an eye on bits 5 and 6 in 'external latch B' (they're used to select 24,25.175 or 36 MHz crystal) and play sound a few notes too low in e.g. modes 30, 31 and 32 so for those screenmodes you should enable the enhancer. Arcemmodes (from Arcem distribution) is installed by default. (If you ever want to run the demo !Jojo, *rmkill Arcemmodes as it and !Jojo disagree about how a certain screenmode should be interpreted). Vidcenh is modelled after VidSwitch from Beebug, there are not many ways to do it differently but I changed the memory requirement (now uses memory on stack) and it does a check on Riscos3 first (as it needs a SWI that only Riscos3 has).

Emulation speed: selected automatically with processortype, but some demos have a high sound samplerate (over 100000 samples/sec)  and benefit from a lower emulation speed, e.g. 8 MHz. And of course, how fast the emulation really is depends on the speed of your host computer and mainly on all the extra work to be done for the video; it's best to limit the max. windowsize of the emulator, and to reduce the colourdepth in your host computer. (256 on Iyonix, RaspberryPi and A9home). Ideally the same as the guest has. Emulation of the videosystem can easily require 2/3 of all available processortime for the emulator. You can also skip frames (#Frames to skip, use the up/down buttons). There's a speed indication to the right, which you also can drag to set the speed exactly. 
It is important to clarify a number of things regarding emulation speeds. Emulation is a timeconsuming process, and your host computer can only do so much. I could have introduced a test loop to see how fast (mega-instructions per second) the emulator runs, but that is also problematic for reasons I will explain. The way it works now is: it constantly compares the time in the host, and the time in the emulated system. If emulated time is faster than hosttime, a timeslice of emulation is skipped. If emulated is constantly slower than host, the emulated time will be lagging behind. The first situation we have with slow emulation clock (8 Mhz) setting, and the other with faster clocks. If in the second situation you measure the speed in the emulator, you will get fantastic emulation speeds (50 K Dhrystones/second) but start up de clock application (!Alarm) and see how slow it runs.
There are several reasons why emulation can be slow:
* for every emulated clock tick, in !ArchiEmu you need 15-25 host clock ticks. So the speed of the host is important.
* if your host processor has a small instructioncache without fast general-purpose memory behind it,(e.g. RiscPC) and a widely varied bunch of instructions to emulate, the emulation code can be too big for the cache and speed drops dramatically to 1/3 or so. If there has to be switched between ArchiEmu assembler and BASIC, and other applications running on the host, meaning that a lot of code&data in the caches need to be swapped, performance is affected badly. A big cache and fast memory surely help.
* What has changed in emulated video memory must be brought to the host screen. If the picture must be stretched, a palette and/or a different colourdepth must be looked up for each pixel and vertical lines must be doubled/quadrupled the conversion process slows down the emulation itself seriously. That's why a low resolution host mode and matching pixeldepths (ie. 16 or 256 colours) are fastest.
The system cannot know beforehand to what extent the emulation is slowed down by videoprocessing or cache load. So I decided not to limit the faster emulation 'speeds' but explain instead why the emulation speeds mentioned by SystemIndex(!SI), Riscosmark or Dhrystone etc can be too optimistic. When singletaskingmode is improved, in the course of development of this program, better methods can be chosen to make singletasking as fast as possible.
In Adaptive mode, the emulated clockspeed is adapted to how fast the host can go, downto 8 MHz. Some processes in the OS-emulation can go wrong if you go much slower (like, it cannot handle interrupts and disc accesses fast enough anymore, resulting in a crash of the emulation).
 
Open Floppypane at startup: whether Floppypane is open or closed when the emulator starts.
In the iconbar menu, you could click on the Floppypane item, if ticked floppypane should be open. You could also drag the entire ArchiEmu Main window to the left, more than half of it over the screen border, and drag it back. That also opens the floppypane.

Enable sound: same for sound. Turning sound on/off can also be done with the menu over the floppy pane.

Left Windows key as Menu: to be used in conjunction with e.g.!WinMenu. !WinMenu is an utility that lets you fake a menu button by pressing the left Windows key. Nice if your mouse only has 2 buttons.


When you're done with configuration, press !Save config (right-lower corner), and then press Reset (right-upper corner). The emulator now should start up. A desktop should be visible. 

When you start up using a game/demo directory, you get some configuration already but you can change it or expand it as you go to the Setup window (iconbar-->setup), change a few bits here and there and save the configuration. Pleease note the demo/game directories are only EXAMPLES, you do not --have-- to use the application in that way; but you can always use e.g. the Riscos3 setup to build your own setup. Change memorysize, processorspeed, change harddiscs, rename the !application and giving it a different !Sprite (matching the !directory name) etc. 

CUSTOMISING
--------------

In its default configuration, an A310 did not have harddiscs. (The default location where to looj for files was floppy 0, if you did *cat you got an overview of the contents of drive 0. You had to change that specifically to :4 (*mount :4) to see the contents of the harddisc. On later machines, e.g. the RiscPC that was different).
So if you have created one or two harddiscfiles, the emulation does not yet know that they are there. We suppose that you have clicked on the iconbar icon (or the emulator has opened its main window straight ahead) and the main window is visible, with the Archimedes desktop in it. You have to configure how many harddiscs the emulation has. In the emulator, on the desktop of Riscos3.10, choose Apps, then !Configure, then Discs. Choose zero to two ST506-discs. No IDE- or SCSI discs yet, the emulator does not know how to handle them. After the warning, the desired number of harddisc icons should appear on the iconbar. On Riscos2 (& still works under RO3) you could hit F12, type in *configure harddiscs 1 (or *configure harddiscs 2), and reset the emulator. (Click on the A icon on the floppypane). When the method using the Confuration utility does not work, use the method: press R12, type in *configure harddiscs 1 (or *configure harddiscs 2) and reset the emulation (iconbarmenu-->resets-->Ctrl-shift-break or Reset button) 
The emulator has to know where the harddiscs are. You should have filled in (or dragged FCD-typed files onto) the writable icons in the Setup window before, see above. 
But nothing is stored yet on these harddiscs. 
Therefore, ensure that you have a floppypane attached on the lower border of the window; do this by dragging the entire Mainscreen to the left, off the screen, and drag it back again. Or open Iconbar menu and tick Floppypane.
Then drag the EmTrsf/adf file (from directory !Riscos2) on the rightmost diskettebay of the pane.This is the thing with the horizontal black stripe, rsembling a floppydrive front opening. Now, in the emulatorwindow again, you can click on the :0 floppy icon. A directory viewer window should open. Also open a harddisc, by clicking on a harddisc icon on the iconbar (inside the emulation). Drag the files on the 'floppy' to the 'harddisc'. You can repeat this for the three Riscos3  floppy images. To transfer more, you can use similar floppy images, or use !EmuTrsf:
 Activate !EmuTrsf by clicking on it. This is a small program that monitors a few drag SWI's, and kicks in action when it detects drags across the window border, then changes the filesave messages that went on inside the emulation. The effect is that you now can drag files and directories across the window border, from and to the environment of your host computer. If single files (no directories) you can even drag them to and from editors (Zap, Paint etc) and to other instantiations of !ArchiEmu. A known shortcoming is that you should not close directories while EmuTrsf is transferring to/from them, especially with selections, otherwise it cannot send messages to windowhandles (when filerwindows close, their handles disappear).
In Apps.!Configure you can also select which type of 'monitor' you want. A multisync monitor allows you to use bigger screens. For instance MODE 31, 800X600. The ARCEMMODES module file is from Arcem, it allows (besides many more) modes 101 and 102 which are 1024 X 768.


There are menus on the floppy pane:

Click on Sound turns on and off the sound; a dialogue window allows you to choose volume; the Wave icon on the right can be dragged to a location on your harddisc, when sound is ticked it will write sound as a Wave-file on your harddisc. Tick 'Stop' if the wavefile is big enough.

Singletask is not very functional yet, it's being worked on, it works more or less now but it's not yet where we want it to be.

MDF management: following the submenu pointer with your mouse, there is a dialoguewindow giving insight in what happens in the VIDC chip. In MDF mode, you can tweak parameters to double/triple screenlines, horizontal pixels, etcetera etcetera. Getting good MDF's is an art that I haven't mastered yet. The generated MDF's are rejected most of the time on LCD's, multisync CRT monitors can have more success. YMMV.

Keyboard gives access to an on-screen keyboard. 

Floppyspeed controls the speed of the floppy emulation. Bigger numbers reduce the time you have to wait until a floppyread/write is ready.

By the way, (it has been described already for the EmuTrsf image, see above) you can drag floppy images to the icons that resemble floppybays, on the pane beneath the main window (aka floppypane). The black stripe will change into a blue one, indicating that there is a 'floppy' inside. Now you can see what's on the 'floppy' by clicking on a floppy icon in the floppypane (the horizontal strip at the lower end of the mainwindow of the emulator, filled with sundry icons resembling the front side of an Archimedes comp.). The emulator recognises fils filetyped &fcd ("Filecore"),&fce ("Floppy") and ffd (Data) - the latter as images with everything in it, so typically 1000000 or 2000000 bytes long. It also recognises Dosdisc images, 360/720/1440K. And /jfd files from Jon Abbot's adffs project.
Menu over the floppybay(s) in the floppypane: if it's empty you can fill it with a readymade, empty diskimage OR (RiscPC or Iyonix) read an image from a floppy in the hardware floppydrive of your host computer. Note this reading-in is a rather slow process because it --expects-- strange things like extra sectors, deliberately broken sectors etc, in short: gamefloppies. You can inspect an image with the viewer, if there are strange sectors it even says that they are strange. Choose Menu on the viewer to change the side or the track etc. On track 79 often strange things occur. Floppies with extra sectors etc. have to be stored in a format different from the usual .adf one; the adi format is invented and contains the sectorheader info as well. Reading physical floppies is also possible for 1600K-floppies, althought Riscos3.10 cannot read them with its fdc1772 floppydrive controller. (if you tell the emulator that it's a harddisc image, the emulated ST506 controller recognises it; lternatively, if EmuTrsf is active and you drag the image from outside the emulatorwindow to inside, to HostFS, harddisc4 or harddisc5, you can inspect it there with !FCFS). In the future, a 3010/A5000 implementation should be able to handle 1600K-floppies. For A310s, Riscos310-ADFS must be changed (and the emulation) to allow reading of 1600K-floppies. 1440K DosDisc floppyimages are understood, though. If the floppyviewer does not work first time, try to quit the !ArchiEmu application and restart.
Writing floppies: You have to have the Machine type right for this, it's in the Setup window reachable from the Iconbar menu. Only RiscPC and Iyonix allow this; iirc MicroDigital's Omega had some floppie problems so if writing floppies from ArchiEmu does work there, I don't know. When an image is loaded, the Write to :0 item is ungreyed. (To write doubledensity images to a high density floppie on the Iyonix you have to cover the dd/hd hole in the floppy casing with something black. Otherwise you can't even DD format such a HDfloppy). To inspect the newly written floppie, you have to dismount the floppy first (the program does that too, but the OS of the host does not notice it:-( ).

To reset the emulation, if the floppypane is open you could click on the "A" of the Archimedes logo. Alternatively there is a Resets menu under the Iconbar menu. Sometimes they seem to hang the application, but press Escape or any other key and all should be well. After Shift-resets it seems that the Shift key remains pressed, then press the Shift keys a few times to 'reset' them.
Monitorwindow: here you can monitor how things are emulated. You can singlestep, set breakpoints, save tracefiles (fill in the number of required instructions, click Trace button, Adjust-click Next, click Trace again, a Tracerfile is now ready to save). There exists a separate program !Tracer available to investigate tracefiles or compare them with another file. Tracerfiles store the contents of all the registers during the tracing timewindow. !Tracer can compare 2 tracerfiles side by side, output lists of called SWI's, make sourcecodelistings (BASIC) of a number of visited locations (e.g. what a SWI does or an FPE instruction), find where in 200 Million instructions a register had contents xxx, etc. This emulator had not been written if !Tracer had not found some very elusive errors.

The Config files have been given the filetype Filecore (&FCD). If you click on them, it starts up an instantiation of ArchiEmu with the settings from this Config. This opens the possibility to create a directory with one or more floppy- or harddisc images and this Config file, a !Boot file, a !Sprites file and a !Run obeyfile that runs the Config file; the floppy- and harddiscfiles in Config should point to the images inside the directory. Config can have a local cmos file in it. For e.g. games the cmos should say (do F12, then *status) boot, drive 0 (for a floppy image) or drive 4 (for a harddiscfile); sound on; configuration in status window should say 'start up in singletasking' and don't forget a keycombimnation to get out again. The harddisc- or floppy images should be autoboooting (inside emulation:for a floppy  F12, mount :0, OPT 4 3, save floppy image back; for a harddisc e.g. HardDisc4,  *mount :4  *OPT 4 3).
Added the possibility to load /jfi files. Remember some of these images predate Riscos 3.11, so you may have to choose Riscos 2 or even Arthur 1.20 first. Best option is to choose the OS with the age of the game, before 1989 is Arthur, before 1992 is Riscos2.
Added hostFS. HostFS depends on two files inside the extnrom directory, hostfs and hostfsfiler. The may have slightly differnet names (with 'RPC' added), Both pairs should work; if one pair does not the other pair will hopefully. They are subsequent versions of the same modules, from Arcem and RPCEmu respectively. The directory that should serve as the Hostfs disc should be mentioned in the Config file, or entered in the Setup window, or the directory or a file from within it should be dragged on the hostfs icon in setup. Make sure that it does not contain a 'harddiscfile' that is in use. Otherwise anything seems to go, Even iso-immages via CDFaker.
Added passing-through of MIDI commands. In principle this is easy, just catch the MIDI SWI's and offer them to the environment of the host, where hopefully MIDIUSB (from Rick Murray) is active. One small problem was that some programs, (Sibelius) emit MIDI_TxCommand whith a time in the future and their issuing should be controlled by a 1000Hz-counter (It's FastClock). 1000Hz ticks are hard to accomplish on RPI etc, but supereasy on an emulator. I used a USB-->MIDI converter from Bespeco and an USB--sound converter model X3M from Serdaco, Belgium:www.serdashop.be. It should connect to USB directly but Riscos does not recognise it then. 

How to prepare a game application-directory.
Create a directory e.g.!Game. The name is unimportant, it may also be !ArchiEmu as long as it's not in the same directory as the one with !RunImage and its !Boot/!Run do not set <RunType_FCD>, and <ArchiEmu$Dir>.
Create a !Boot file (in an editor, it should have filetype Obey) containing the text 'Iconsprites <Obey$Dir>.!Sprites'     (without the '' of course). A boot file is not required, however. Filer looks up sprites even if !Boot files are missing.
Create a !Run file (also Obey filetype) containing '/<Obey$Dir>.Config'
A Config file (it's a text file actually but it has been given filetype &FCD aka Filecore). You can fill this file with all sorts of info but it SHOULD contain the name(s) of the harddiscfile(s) or the floppy(-ies) that the emulator needs; CMOS may be included in the config file or a CMOS directory must be there, start up in singletasking YES, it should have the Operating system and RAM size required for this game. It's safest to choose OTHER as the machine type. Safer if you transfer the Gamedirectory to a different computer.
The CMOS should be set as *configure boot , *configure drive 0 (if a floppy contains the game and the emulator should boot from :0) or *configure drive 4 (if it should boot from harddisc :4). You can do this with the Configure application in Riscos3 or from the commandline in the emulation, F12 and *configure... etc. 
The icon (in setup) 'determined by what's available' should be there, not 'by cmos'. Or you should take care that cmos and available floppy/hd images match.
Of course you can configure more floppies and harddrives as long as you include the images in the !Game directory. If the path starts with '%config.' the emulator knows where to search. Also if you use floppy images in !Game, the item 'Load floppies at startup' should be ticked.
Drag the necessary floppy/harddisc images into the !Game directory.
Keep a safe copy of Config from the !ArchiEmu directory.
Now start up the emulator on it's own, (not from clicking on the game directory yet).From the iconbar menu, choose Setup. Set the options as required and Save (with the draggable icon) the Config file to the !game directory. Then, drag the main floppy to floppybay 0 (Or fill in the name of the important harddiscfile in the Setupwindow writable icon #5, and Reset). Open floppie or harddisc, locate the !Sprites file of the game, load it into !Paint. Activate !Emutrsf. Drag the game icon from Paint inside, to the !game directory outside and rename it to !Sprites. Finally, add a !Boot file to the floppy or harddisc saying something like : run $.<name of main game directory on that floppie> e.g. run $.!E-Type
Make the 'floppie' or 'harddisc' autobooting:  *mount :0 (for a floppie) or *mount :4 (for a harddisc), then *OPT 4 2
If it's a floppie: save it back from the floppie bay into the new !game directory.
If needed, rename the sprite from !Sprites to something that matches the name of the !game directory.
Have a look with a text editor in the Config file, make sure that the paths of the harddisc- and floppiefiles and cmos start with   %config    . If you want a snow emulation while the emulated video circuitry is still idle, also add snow:on. (normally it is omitted as it is silly).

Make sure to restore the old config file to the !ArchiEmu directory.

So a Game directory should contain !Boot,!Run,!Sprites,Config, and one or more floppie and/or harddisc images. This setup also makes it possible to have !ArchiEmu in !Boot.Resources and different setups separately all with their own OS preference and harddiscs and floppies.
The config file has filetype Filecore, or &FCD. This is the same filetype that !FCFS triggers on. FCFS is/was an application that enabled you to look inside floppy- or garddisc images and use them like a drive, similar to what DOSFS, SparkFS etc. do. If !FCFS has been seen, you can expect an error like "Application may have gone wrong .. " and the explanation is 'Module FCFS is not 32-bit compatible'. In that case press F12, type unset Alias$@RunType_FCD, press Return, and back in the desktop click on $.!Boot.Resources.!ArchiEmu.!Boot  

Some software URL's:
If you have FTPc (an FTP client, by Colin Granville) you could choose from its iconbarmenu and try some of the servers there, eg. the Stuttgart server.
Various utilities and  gamefloppies (.ADF images) are on http://acorn.revivalteam.de
http://www.drobe.co.uk/archives/
www.apdl.org.uk or the webarchive site: https://web.archive.org/web/20140531201611/http://www.apdl.co.uk/
www.archive.org, choose Software in the bar at the top, from there go to TOSEC or the CDROM's, there are Archimedes, BBC and Electron categories. The latter two can be emulated with 6502Em or 65Host, (or with 6502Em or BeebIt directly  - but you don't need ArchiEmu then..) (A.t.m. Elc2 can run unzipped UEF's and ADF images).
www.4corn.co.uk   downloads and links to other URL's.
Some floppie images from the JASPP site can be used too, first unzip them and drag them onto the floppydisc bay south of ArchiEmu's mainwindow.
www.arcarc.nl also has a lot of software, some in hfe format which this emulator can use, too. 

!6502Em: http://www.borcherds.co.uk/murklesoft/riscos/6502em.html
!BeebIt:http://homepages.paradise.net.nz/mjfoot/bbc.htm

Copyright
This is 'Don't bother me' software which means:
Use it on your own risk. DO NOT apply it for uses that could endanger lives (whether human or animal) or economic loss.
You are free to use the methods and thoughts behind this application and emulation-methods in your own programs, also for programs that you sell for profit, insofar as you never will charge me or confront me in court if I continue to use these methods that are used here. If you want to start a fork on the basis of this program, you are free to do so but do not bother me with questions about derivations.
When I have more time I plan to write up an explanation of the emulation method, which is an intermediate between JIT and interpretation, etcetera. And I should look at more appropriate types of IP licensing like EUPL. In the meantime, I'm sorry that the source is hardly understandable at places; especially assembler is register-optimised, as a consequence it is unreadable. 

 


enjoy


Jan de Boer.
jandeboer@telfort.nl
http://www.tellima.nl












