RPCEmu Linux Guide

Introduction
This quick guide describes how to download/install/configure RPCEmu for your Linux environment. The guide is written for a Debian Linux distribution like Ubuntu, Knoppix and Xandros. This doesn't mean it won't work on other Linux distributions but commands, package names and places of files could be different from those described in this guide.

Notably for RPM-based distributions like Fedora or SUSE the apt-get command won't work to install packages... try using yumex to search for similarly-named packages to install. If you have success then please list the package names you used below.

Other Unix-like platforms such as FreeBSD or Mac OS X may work - feel free to add details of your experiences here or post to the RPCEmu mailing list. There is also a Windows version of RPCEmu which you may be able to build from source - just try the SVN sources or ask the list for more details.

If you have any problems, see the Troubleshooting section or known RPCEmu issues.

Requirements
What do you need:
 * Linux system: for best results P4 or similar processor at about 2GHz or more.
 * A working X Window system (X11)
 * Internet connection
 * Harddisc space: 62 MB for the emulator and 500 MB for RISC OS applications
 * Image files of RISC OS ROMs 3.6, 3.7, 4.02 or 4.39 (best is RISC OS 4.02). You can buy 4.02 ROM images for £5 from RISCOS Ltd.

Install RPCEmu
Open a terminal window. Get the required packages for the RPCEmu emulator by using apt-get:

sudo apt-get update sudo apt-get install build-essential subversion liballegro4.2 liballegro4.2-dev liballegro4.2-plugin-jack unzip wget

Get the lates RPCEmu package with subversion. If you have a firewall for outgoing traffic you may need to open TCP and UDP port 3690 to allow this.

svn co svn://svn.riscos.info/rpcemu/trunk rpcemu

After downloading:

cd rpcemu/src/ aclocal automake autoconf

If you get an error that the system doesn't recognize any of the above commands then install the next packages:

sudo apt-get install make automake autoconf

You can get some warnings from the allegro library, just ignore them.

Now you have two options. Create the interpreter version of rpcemu or the dynamic recompiler. The first one is slower but more stable and it's possible to select an ARM processor. The recompiler version has the advantage to be five times faster but only runs the StrongARM (SA) processor. If you want to run the SA processor under RISC OS 4 then I recommend the recompiler because of a current problem in the interpreter with bad screen redraws and abort on data transfers in 16 bits per pixel modes. The dynamic recompiler only works on x86 host processors.

To select the interpreter:

./configure

To select dynamic recompiler:

./configure --enable-dynarec

Some output of the configure command

If you see the output and get no errors then compile:

make

If there were no errors then the emulator is ready for use. Go back to the rpcemu directory:

cd ..

Install ROMs in place
To get the emulator running you only need the RISC OS ROMs. There are currently two easy ways to do this.

Purchase ROMs from RISCOS Ltd
The RISC OS 4.02 ROM image is available to buy from RISCOS Ltd. Once downloaded to your harddisc, extract the file ROM402 into the roms directory. You need to rename the file rom:

mv ROM402 rom

Extract ROMs from a working computer
Alternatively, if you have a working RiscPC or similar, you can extract the ROMs as files from that. I recommend to get RISC OS 4.02 because it has more support for internet (RISC OS 4.39 hasn't been as well tested). As RISC OS is copyrighted, you have to get them yourself from a real RiscPC. Just open a taskwindow (press CTRL+F12) on your RiscPC and enter the next commands:

*save rom1 03800000 03900000 *save rom2 03900000 03A00000 *save rom3 03A00000 03B00000 *save rom4 03B00000 03C00000

Get the 4 files (rom1 rom2 rom3 rom4) to your linux host system and copy them to the roms directory.

Install RISC OS boot image
Having put the ROMs in place, now you need the RISC OS boot image. If you have the wget package then download the bootimage:

wget http://b-em.bbcmicro.com/arculator/hdboot.zip

Otherwise download the archive from the site with your browser - try right clicking and using 'Save link as...' to choose where it puts the download. Extract the archive to the rpcemu directory and overwrite cmos.ram and hd4.hdf</tt> with those inside the archive using:

unzip hdboot.zip

Create two directories in the rpcemu</tt> dir:

mkdir hostfs mkdir poduleroms

Edit rpc.cfg</tt> in the rpcemu</tt> dir: mouse_following = 1 cdrom_type = 0 cdrom_enabled = 1 blit_optimisation = 0 refresh_rate = 60 stretch_mode = 0 sound_enabled = 1 vram_size = 2 cpu_type = ARM710 mem_size = 32 ipaddress = 172.31.0.1 (you should be able to double click a .cfg file to edit it, or type nano rpc.cfg</tt> for a simple editor)

Start up the emulator in your X11 environment:

./rpcemu

A window will pop up and the emulator loads the OS and runs the Boot system. You've got a working RISC OS desktop on your linux system.

Booting from EmuFS
RPCEmu revision 164 and higher uses a new filing system to communicate between RISC OS and the host filing system. This new FS is called EmuFS. It works internally as the previous filesystem HostFS but it has more advantages like multiple disc support, free support, multiple language support and a better disk filer.

The EmuFS modules will be loaded by RISC OS at boot time from the poduleroms</tt> dir. Check that your poduleroms</tt> directory contains the modules emufs.1 emufs.2 emufs.3</tt> and check that the dir hostfs</tt> exists in the rpcemu</tt> dir.

Edit rpc.cfg in the rpcemu dir</tt> and remove the underscore from the [hostfs_]</tt> item. Your rpc.cfg</tt> file should be like this now:

[hostfs] ; When you want to use EmuFS under RISC OS: ; 1. Create a directory hostfs in emulator dir ; 2. Remove the underscore in above section identifier hostfs.drive0.name = Boot hostfs.drive0.path = ./hostfs hostfs.drive0.permissions = read,write hostfs.drive1.name = Home hostfs.drive1.path = ~ hostfs.drive1.permissions = read hostfs.boot.drive = 0

Run the emulator and wait till the system has been booted. The iconbar shows now two extra EmuFS disc icons called 'Boot' and 'Home'. Open the Filer window of the 'Boot' disc. This disc is linked to your previously created hostfs</tt> directory. It's now empty but you can use this disc to transfer files from the host system to RISC OS and back. The ADFS harddisc where the system boots from is linked to an image file hd4.hdf</tt> on your host system.

Open !Boot</tt> (shift doubleclick) on the bootdisc. Go to directory <tt>Choices.Boot.Task</tt> and remove the application <tt>!hostfs</tt>. It's important to do this because HostFS is now obsolete.

Copy <tt>!Boot</tt> from 'IDEDisc4' to EmuFS disc 'Boot'.

Now press F12 and enter the command:

*configure filesystem EmuFS

An example of how your desktop looks like when you're at this step

Return to the desktop, shutdown RISC OS and quit the emulator.

Enlarging emulated ADFS drive
So far we've set the emulator to boot from EmuFS. So you can put !Boot and all your files on EmuFS and have them accessible from RISC OS and Linux. A few applications may not like this, so you can also create an emulated ADFS hard drive as follows:-

Get HForm from the Arculator website and unzip it:

wget http://b-em.bbcmicro.com/arculator/rpchform.zip unzip rpchform.zip

It's a floppy disc image which unpacks to hform.adf - we'll now make this appear as an ADFS floppy drive.

Boot the emulator and press CTRL+END. A menu pops up at the left top. Select 'Disc' -> 'Load drive :0...'. Select <tt>hform.adf</tt> and press 'OK'. Open drive 0 (click on the :0 icon at the iconbar) and run <tt>!HForm</tt>. Format the ADFS bootdisc with these options:

Drive: 4 Retain shape: No Drive type: OTHER Sectors per track: 63 Heads: 16 Cylinders: 1024 Drive parameter init flag: 1 Parking cylinder: 1023 No more changes to defect list Initialise the drive Soak test: None Bootable disc: Yes Longfilenames: Yes (only available for RISC OS 4) Confirm format: Yes Large file allocation unit (LFAU): 2048

You have created a large harddisc image of 504MB for ADFS drive 4. If you want a bigger image then enlarge number of cylinders. Note that the parking cylinder must be the total amount of cylinders minus 1 (it isn't used for the formatting, but other values may confuse HForm). Note also that you have to multiply the suggested LFAU value by 2. So if HForm suggests 1024 then change it to 2048.

HForm in action on ADFS drive 4

Installing RISC OS 4 Boot system
Go to directory <tt>hostfs</tt> and download the RISC OS 4 Boot installer archive from the riscos.com site:

wget http://support.riscos.com/Support/Releases/RO4install.zip mv RO4install.zip RO4install,ddc

As you probably don't have a dearchiver for RISC OS get SparkPlug:

wget http://www.davidpilling.net/splug.bas mv splug.bas splug,ffb

Open the EmuFS 'Boot' disc in RISC OS and run the basic file <tt>splug</tt>. After !SparkPlug has been created, doubleclick on the archive file <tt>RO4install</tt> and extract <tt>!RO4Install</tt> to your Harddisc4 disc. This can take some minutes (look at the SparkPlug icon to see if the extracting has finished).

Now you can install the RISC OS 4 boot sequence to either the emulated ADFS drive or EmuFS. The following instructions are for ADFS:

Doubleclick on the RISC OS 4 installer, drag the !Boot icon to the filer window of Harddisc4, click on 'Continue' and in the next dialogue click on 'Start install'. Click on 'Continue' in the warning window and click on 'Continue' in the next dialogue. Wait till the installer is finished and click 'Continue' again. In the next dialogue click 'Continue' to install Apps and Utilities. After installation click 'Exit'

The complete RISC OS 4 Boot install process

Press F12 and enter the commands:

*configure filesystem ADFS *configure drive 4

Return to the desktop.

To install on the EmuFS 'Boot' disc the install is the same, only drag the !Boot to the EmuFS filer window, you don't need the *Configure commands.

Shutdown RISC OS and click 'Restart' to boot the OS with the new Boot. You now have a fully working Boot with the standard RISC OS 4 apps and utilities.

CD-ROM support
Check if the symbolic link <tt>/dev/cdrom</tt> points to your CD-ROM device at the host system. You can check this by trying to mount this device to a directory. Insert a data CD-ROM in your drive and enter the commands:

mkdir ~/cdrom sudo mount /dev/cdrom ~/cdrom ls ~/cdrom

If you don't get any errors and see the contents of the disc then the link works. If not, your distro may have automatically mounted it somewhere else. Try this: mount If you have a line in the output that looks something like: /dev/dvd on /media/cdrom type iso9660 (ro) then your CD-ROM is called /dev/dvd (or it may be called /dev/scdX where X is a number). Make a symbolic link of this to /dev/cdrom: sudo ln -s /dev/dvd /dev/cdrom and try the above three commands again.

Now unmount the disc and remove dir <tt>cdrom</tt>:

sudo umount ~/cdrom rmdir ~/cdrom

Edit <tt>rpc.cfg</tt> and check if:

cdrom_enabled = 1

Start the emulator and open the RPCEmu menu. Select 'Settings' -> 'CD-ROM' -> 'IOCTL'.



Double click the !Boot icon on the RISC OS bootdisc. Select 'Discs' in the configuration dialogue, configure one CD-ROM drive and click on 'Set'.

Click 'OK' in the next warning dialogue. Open the CD-ROM by clicking the CD-ROM icon :0 at the left of the iconbar.

It's also possible to mount ISO images instead of real CD-ROM's with RPCEmu. Open the RPCEmu menu and select 'Settings' -> 'CD-ROM' -> 'ISO image...', select an ISO image to mount and click 'OK'. Open the CD-ROM image by clicking the CD-ROM icon :0 at the left of the iconbar.

Note every time you start RPCEmu, you have to select 'IOCTL' or 'ISO image...' to enable CD-ROM support.

Network support
RPCEmu uses a TAP tunnel device to send packets between the emulator and the host system. Unfortunately these devices can only created by root, therefore RPCEmu must be run as root. So to enable it you have two options:

1. Use sudo to start RPCEmu:

sudo ./rpcemu

RPCEmu will automatically drop root privileges as the tunnel has been created. This has a disadvantage that you have to enter a password to get RPCEmu going.

2. Make root the owner of the rpcemu binary and set the user s-bit. Enter the two commands:

sudo chown root rpcemu sudo chmod u+s rpcemu

And edit <tt>rpc.cfg</tt> to add this line:

username =

In this case RPCEmu will also drop root privileges after the tunnel has been created.

Check <tt>rpc.cfg</tt> for the IP address. It should be:

ipaddress = 172.31.0.1

Run RPCEmu with root privileges. You should not get messages like:

Error setting TAP on tunnel device: Operation not permitted Networking unavailable

Check if the emulator has created a tap interface and that it's IP address has been set to 172.31.0.1:

ifconfig -a

You should get something like this:

tap0     Link encap:Ethernet  HWaddr 00:ff........... inet addr:172.31.0.1 Bcast:172.31.255.255  Mask:255.255.0.0

Next try to ping the interface:

ping 171.31.0.1

You should get something like this:

PING 172.31.0.1 (172.31.0.1) 56(84) bytes of data. 64 bytes from 172.31.0.1: icmp_seq=1 ttl=64 time=0.079 ms 64 bytes from 172.31.0.1: icmp_seq=2 ttl=64 time=0.069 ms

Get the latest !System from RISC OS Open:

cd hostfs wget https://www.riscosopen.org/zipfiles/platform/common/PlingSystem.zip mv PlingSystem.zip System,ddc

Copy the <tt>EtherRPCEM</tt> directory from <tt>riscos-progs</tt> to the hostfs dir:

cp -r riscos-progs/EtherRPCEm/ hostfs/

The AppleTalk module in RISC OS 4.39 conflicts with EtherRPCEm: loading EtherRPCEm hangs RISC OS if AppleTalk is loaded. Before installing EtherRPCEm prevent the AppleTalk module from being loaded by deleting or renaming !Boot.Resources.!System.420.Modules.Network.AppleTalk (for example, you could rename it to AppleTalkD, this will prevent it from being loaded automatically but keeps it around in case you want to rename it back in future).

In RISC OS open the EmuFS 'Boot' disc and extract archive <tt>System</tt>. Doubleclick on <tt>!SysMerge</tt>. Open dir <tt>EtherRPCEm</tt> and copy <tt>!Boot</tt> from the EtherRPCEm dir on the <tt>!Boot</tt> of your bootdisc. Run <tt>!Boot</tt> and click 'System' to open the System merge dialogue. Drag <tt>!System</tt> from the <tt>EtherRPCEm</tt> dir to it and click 'Merge'.

Click 'Network' in the configuration dialogue and click 'Internet' in the next dialogue. Enable 'TCP/IP Protocol suite' and click on 'Interfaces'.

Enable 'RPCEmu' interface and click 'Configure...'. Set these settings:

Obtain IP address: Manually IP address: 172.31.0.2 Netmask: 255.255.0.0

Click 'Set' and 'Close' in Interfaces dialogue. Open the Routing dialogue and set these settings:

Gateway: 172.31.0.1

Click 'Set' and open the Host Names dialogue. Set these settings:

Host name: rpcemu Local domain: riscoslocalnet.invalid Primary name server: use 1st IP address from output command cat /etc/resolv.conf Secondary name server: use 2nd IP address from output command cat /etc/resolv.conf Tertiary name server: empty or 3rd IP address from output command cat /etc/resolv.conf Name resolver module: Resolver Acorn Enable Use name server also

Click 'Set' and 'Close' in the Internet configuration dialogue. Next Click 'Set' in the Network configuration dialogue and click 'Reset now' in the next question dialogue.

After the emulator has booted open a taskwindow (CTRL+F12) and enter:

*ifconfig -a

You should get something like this:

lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 inet 127.0.0.1 netmask 0xff000000 rpcem0: flags=8863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 172.31.0.2 netmask 0xffff0000 broadcast 172.31.255.255 ether 00:00:00:00:00:00

Next try to ping 172.31.0.1 (the emulator gateway) and your host system IP. If that works fine you only have to configure the host system to enable packet forwarding. If you're running a firewall package on your host system then it's recommended to use it to configure port forwarding. You can also enable forwarding by using these commands on the host system after RPCEmu has started (you'll need to re-run these every time you boot the host machine):

sudo iptables -I FORWARD -m state --state ESTABLISHED,RELATED -j ACCEPT sudo iptables -t nat -A POSTROUTING --source 172.31.0.0/16 -o eth0 -j MASQUERADE echo "1" | sudo tee /proc/sys/net/ipv4/ip_forward echo "1" | sudo tee /proc/sys/net/ipv4/ip_dynaddr

This will forward packets out to the eth0 interface. You'll need to replace eth0 with your outgoing internet connection. To find this on the host system, do: route -n The output might be something like this: Kernel IP routeing table Destination    Gateway         Genmask         Flags Metric Ref    Use Iface 172.21.114.0   0.0.0.0         255.255.255.0   U     0      0        0 eth1 169.254.0.0    0.0.0.0         255.255.0.0     U     1000   0        0 eth1 0.0.0.0        172.21.114.65   0.0.0.0         UG    0      0        0 eth1 Find the line with Destination set to 0.0.0.0: this is your default route. Here the Iface is eth1. So replace eth0 with eth1 in the iptables command above. If you change network environment, maybe from wired network to Wi-Fi, you may need to recheck this value.

Try to ping some hosts on the internet from the emulator like google.com, riscos.com etc. If that works you are connected to the internet with RPCEmu.

If you want to allow access to servers running on the emulator from the Linux machine or other machines on the network you'll need to add additional forwarding rules. Consult a guide on iptables for how to do this.

Note that for the moment ShareFS won't work since it'll need some more iptables rules to forward UDP broadcasts (ports 32770/32771/49152/49171) from the host.

Installing NetSurf
Go to the hostfs dir and download the latest NetSurf from http://www.netsurf-browser.org or use wget:

wget http://www.netsurf-browser.org/downloads/development/netsurf.zip

Rename <tt>netsurf.zip</tt> to <tt>netsurf,ddc</tt>. Start the emulator and create a dir <tt>Internet</tt> on your bootdisc. Extract the contents from the netsurf archive to this dir. Use the Boot Merge (click 'Boot' and then 'Install' see below) and and the System Merge facility to merge <tt>!Boot</tt> and <tt>!System</tt> from the <tt>Internet</tt> dir to your boot system. Next reboot the emulator and start <tt>!NetSurf</tt> from dir <tt>Internet</tt>. Enter a valid url in the top bar and you're on the world wide web.

RISC OS won't boot properly, or behaves oddly
As on a real RISC OS machine, it uses the CMOS RAM to hold important system settings. In the emulator these are stored in the cmos.ram file. If you use the emulator for the first time, or change the version of RISC OS you're running, you need to reset the CMOS. To do this, start the emulator while holding down the Delete key. Just as it would on a real machine, it resets the CMOS to factory settings for the version of RISC OS you happen to be running.