Roll your own RISC OS 3.1x

chat about arc/risc pc gaming & RISC OS software here (NOT the core OS!)

Related forum: adventures

User avatar
Posts: 592
Joined: Tue Sep 22, 2009 10:29 am

Roll your own RISC OS 3.1x

Postby flibble » Tue Dec 05, 2017 12:11 am

Following on the discussions in the 'RISC OS 3.20' thread I thought I'd relearn how to use some very old programs and thought people might appreciate some 'tutorial' style instructions.

Roll your own RISC OS image

These are some basic instructions that will hopefully allow you to roll your own custom RISC OS ROM image for 3.1x era machines. It doesn't discuss burning ROMs for use in real hardware as I have never taken it that far.


Mainly, just because. You can add updates from Acorn and other companies that would normally need 'softloading' (aka loading into RAM), thus saving memory and fixing some of the bugs. You can also add your own apps to the ROM, or even just customise it with your own sprites. You could have an idea for a custom embedded use for a machine, this will allow you to ship a ROM only version.

  • A RISC OS 3.1x ROM image, 3.11 will be used in these examples.
  • Two instances of an emulator capable of running RISC OS 3.1x, one will be used for building (the build machine), one used for testing (the test machine). HostFS will be incredibly useful here, so either RedSquirrel or Arculator (if compiling from source).
    I used arculator in this example.
  • Software on the build machine
  • Ideas for what you want to add to the ROM
    • Official Acorn updates such as Newlook, the universal boot, !System updates etc
    • Your own or someone else's apps so they are always available.
    • Third party modules
    • Changing the version number so you can be the first to run RISC OS 7


Binary munging ROM images like this is prone to making mistakes, you'll find some software and modules are not capable of being placed in ROM (e.g anything that uses temporary disc files relative to its install, or anything that writes to its own module space as workspace). Certain modules have cross dependencies that need to be figured out. You have a hard constraint on the size of the ROM, so sometimes you have to pick what to leave out when you add your own stuff.

Though probably the biggest caveat is that this has not actually been overly tested and certainly not on real hardware. It should work, but do not use one time programmable ROMs until you test it.

However if you find bugs in the builder or shortcomings, please report them as we may be able to fix them.

Phase 1 - RISC OS 3.11 with an extra ROM module

Setup an emulator image with RISC OS 3.11 for the build machine. Install !Sparkplug, optionally install !Zap.



Run 'LocalDir' to set the working directory to the ROMBuilder directory.
Run 'CreateList' to create a manifest for your new ROM based on the contents of the RISC OS 3.1 ROM you're running, in the file 'ModuleList'


As you can see 'ModuleList' contains a list of entries to put in the ROM and the place the 'Build' program should load them from.

The choices for places are
ROM: The module from the running version of RISC OSs ROM image
RMA: The module from RAM having been loaded from disc earlier (I don't use this option really)
Disc: A named module in the 'Modules' subdirectory of the 'ROMBuilder' directory
Bootstrap, taildata, SET: don't worry about these yet, we'll come back to them

Add a module,

For this example I'm going to use the OSVersion module, it changes the output of *FX0 to a custom string, which should make it nice and obvious that we have a new ROM.

Download to the build machine, optionally edit the version number string in 'MakeMod' and rerun it, place the OSVersion module built into the 'ROMBuilder.Modules' directory.


Next edit the 'ModuleList' manifest file, and add this module into the image at the end, but before the SET: and taildata: section.


Now run 'Build' to make your ROMImage, this creates the file 'ROMImage' in the 'ROMBuilder' directory.


Copy this 'ROMImage' file out of your build machine, via hostfs and place it in the ROMs directory of your emulated test machine, boot up and cross your fingers.


Pat yourself on the back, you've just built your first ROM.

BUG: ROM Image generated is 2049Kb in size not 2048Kb, investigating.

Phase 2 Changing resources in ResourceFS
Manu newer RISC OS modules also need newer resources (such as templates, messages files, icons) to work properly, these are stored in ResourceFS. ResourceFS is the files you can see when you middle click over 'Apps' and click 'Open '$''.

You can add or remove to these files by editing the 'Messages' module, to edit it use the Messages program.
(134.9 KiB) Downloaded 5 times

Unzip this file in your host operating system direct into the hostfs directory of your emulator.

To run the Messages program, we also need a copy of the CallASWI, SharedUnixLib and FPEmulator modules to be available.
(16.84 KiB) Downloaded 2 times

Also unzip this to the hostfs directory of your emulator and double click to load them ... this is because I'm being lazy and don't want to setup a full boot sequence for this build machine. You'll need these module loaded every time you reboot and want to run the messages programs


Next we need a copy of the RISC OS 3.11 Messages module to work with, using !Zap, middle click on the iconbar icon and select 'Create' -> 'Get Module' and pick 'Messages' from the list. Save a copy of the module from Zap to the messages directory.

Whilst you're looking at the module code we need to determine what the r0 argument is to the SWI XResourceFS_RegisterFiles and XResourceFS_DeregisterFiles. It's not very obvious in the 3.11 module, but it should be E0 in hex.

This offset is where in the module the chain of files stored starts and differs between versions of the Messages module.


Enter the messages directory, double click 'ThisDir+', create a directory in the messages directory called 'Working'


Start a task window and enter the following

*read Messages e0


This takes a while to run but afterwards, in the directory 'Working' you will have the directory tree of all the files in the Messages module.


Making a change

For this example, we will try something very very simple, we'll create a basic file and save it to the top of the resource tree


Rebuilding the Messages module

Again, from a task window, make sure you're in the messages directory and enter the following



This creates a new module called 'Output', copy this file to the ROMBuilder.Modules directory and rename it to Messages.

Edit the ROMBuilder.ModuleList file and change the entry for Messages from ROM: to Disc:, to use our newly created version.


Then build the romimage in the same way we did in Phase 1. Double click 'LocalDir' and double click 'Build'

Again copy the romimage out to your test emulator and run.


Why this is almost competent

Phase 3 Adding lots more and trying to be clever

Coming Soon!

Posts: 1711
Joined: Sun Nov 25, 2012 12:43 am

Re: Roll your own RISC OS 3.1x

Postby steve3000 » Tue Dec 05, 2017 12:44 am

Ooh very nice :)

Do the build tools include calculating the ROM checksums and a tool to generate 'striped' 8 bit or 16 bit ROM image files for burning? (The later is simple to write if not...)

User avatar
Posts: 592
Joined: Tue Sep 22, 2009 10:29 am

Re: Roll your own RISC OS 3.1x

Postby flibble » Tue Dec 05, 2017 2:09 am

steve3000 wrote:Do the build tools include calculating the ROM checksums and a tool to generate 'striped' 8 bit or 16 bit ROM image files for burning? (The later is simple to write if not...)

I don't believe there's checksum code in there. I think the Striped versions are made from the programs SplitPage and SplitWord are for, but have never tested.

User avatar
Posts: 592
Joined: Tue Sep 22, 2009 10:29 am

Re: Roll your own RISC OS 3.1x

Postby flibble » Wed Dec 06, 2017 10:26 pm

now with Phase 2 instructions in original post.

Return to “software”

Who is online

Users browsing this forum: No registered users and 3 guests