<div id="toc_heading"></div><div id="toc"></div> h2. Introduction h3. History, RISC OS 5 and software compatibility Early ARM processors had a combined 26-bit program counter and status register, rather than separate 32-bit program counter and status registers. For a time processors had both 26-bit and 32-bit modes, with the former being phased out by ARM. In October 2002 RISC OS 5 was released using only the 32-bit mode, required because 26-bit mode processors were no longer available - the last being the StrongARM used in the RiscPC. Most software written in BBC BASIC has no compatibility issues, and in many cases software written in C merely requires a recompilation of the source code, where available. However, some software is reliant on features specific to 26-bit mode and needs updating before it will work. A "RISC OS 5 ROM upgrade":/content/sales/risc-os-roms is available to install on real hardware (Risc PC/A7000/A7000+). The following installation notes will allow you to run RISC OS 5 under emulation on an Apple Mac running macOS. <notextile> <p><div style="background-color: #FFCCCC; border: 1px black solid; padding:0.5em"> <b>Note:</b> If you wish to run RISC OS 5.2x any legacy applications with 26 bit code will first need updating.<br />If you wish to run legacy programs then a software compatibility tool called <a href="http://sendiri.co.uk/aemulor/">Aemulor</a> can assist in running 26 bit applications in a 32 bit operating system. </div></p><br /> </notextile> h2. Installing RPCEmu from scratch A "development build of RPCEmu 0.9.4 for 64-bit versions of macOS":https://github.com/Septercius/rpcemu-dev/releases is now available. This build is known to work on macOS 13 Ventura and macOS 14 Sonoma. If you have an older version of RPCEmu already installed, see "Upgrading from an older version of RPCEmu":#Upgrade below. h3. Installation # Download the zip archive of "RPCEmu 0.9.4a":https://github.com/Septercius/rpcemu-dev/releases - be sure to get the ZIP archive, not the DMG package. # Open the zip archive, and copy the applications "RPCEmu-Interpreter" and "RPCEmu-Recompiler" to the Applications folder (either drag them over the Applications entry in the Finder sidebar, or onto the Applications folder on the dock). # Create a data folder within your Documents folder (e.g. <i>Documents/RPCEmu</i>) and copy the contents of the "Data" directory from the RPCEmu distribution archive. # Download an IOMD ROM image from "the downloads page.":/content/downloads/riscpc The recommended ROM is labelled <b>IOMD 5.30 stable (softload)</b>. # Unpack the ROM archive and copy the file <b>"riscos"</b> from <b>soft/!Boot/Resources/SoftLoad/riscos</b> into the <b>Documents/RPCEmu/roms</b> directory. The other files aren't needed and can be discarded. # Download a HardDisc4 image from the "Miscellaneous downloads":/content/downloads/common page. The recommended version is labelled <b>HardDisc4 (self-extracting)</b> - this should give you a file called "HardDisc4.5.30.util". # Copy this file to <b>Documents/RPCEmu/hostfs</b> as <b>"HardDisc4-util,ffc"</b> - take care to add the <b>,ffc</b> (comma ffc) ending which will be translated by RPCEmu to produce the metadata filetype for RISC OS. <b>Note 1:</b> RISC OS 5 beta versions are updated frequently with nightly builds from the Git repository but may contain bugs, so important data should only be trusted to the stable installs. <b>Note 2:</b> RPCEmu is deemed alpha quality by its authors, which rather negates any comments about stable installations in note 1. In practice, many people use RPCEmu without issue. <b>Note 3:</b> If you choose to use a beta ROM it is best to use the matching beta HardDisc4 as changes in the ROM may require specific disc based components. h3. Configuration These instructions are for setting up RPCEmu-Interpreter: this is the emulator that works on all Macs (i.e. both Intel and Apple Silicon processors). # Open the Applications folder and double-click on the <b>RPCEmu-Interpreter</b> icon to launch it (you may need to right-click and choose Open for the first time, as newer versions of macOS try to discourage running potentially unsafe code). # A dialogue box will appear, asking you to choose a data directory &#8211; choose the <b>RPCEmu</b> folder created earlier. # Ignore the TaskManager error and click on the <b>RPCEmu</b> item in the menu bar and then <b>Preferences&#8230;</b> # Select the SA110 (StrongArm) processor option, select 256MB <span class="caps">RAM</span>, and 2MB <span class="caps">VRAM</span>. You may also wish to enable sound. # Quit and re-open <b>RPCEmu</b> (it may not auto-restart for you). # After the restart the emulator will stop at a * prompt. This is because the system is not currently configured correctly to boot into the desktop - type <b>desktop</b> to start the desktop <span class="caps">GUI</span>. Cancel the error 'Machine startup has not completed'. # Click HostFS, on the iconbar, to open the root directory. # Double-click on the HardDisc4-util to extract the HardDisc4 contents. Wait a while. Double-click the HardDisc4 directory that has been created to open it. Cancel the error 'No Boot application has been run', and hold shift down while dragging the entire contents of HardDisc4 to HostFS:$ (this moves, rather than copies, everything to the root). # Press f12 and issue the following commands <b>Configure FileSystem hostfs</b><br> <b>Configure Boot</b><br> <b>Configure SystemSize 32K</b><br> # Press enter twice to return to the desktop then press Ctrl-Shift-F12 to shutdown. # Click the macOS Close button. # Click on the <b>RPCemu-Interpreter</b> icon in the Applications folder to re-launch RPCEmu. # When RPCemu is launched, it should now boot to the desktop. All further configuration of <span class="caps">RISC</span> OS is personal preference. Access the configuration section of <span class="caps">RISC</span> OS by a single click of the Menu (middle) mouse button over the cog icon on the far right of the iconbar. If you have an older (Intel-based) Mac running macOS 11 Big Sur, macOS 12 Monterey or macOS 13 Ventura, you can use RPCEmu-Recompiler in addition to RPCEmu-Interpreter. Simply repeat steps 1-5 above for RPCEmu-Recompiler. h3(#Network). Networking The explanation over on the <b><a href="http://www.marutan.net/rpcemu/manual/net-ro-nat.html">RPCEmu web site</a></b> works reliably on the <b>NAT</b> option, but the bridging option is untested. <b>Emulator configuration</b> Run RPCEmu and open the networking configuration (up on title bar) # Click Settings # Click Networking # Select the "Network Address Translation" option and click OK. The Emulator will restart. <b>RISC OS Networking Configuration</b> When RISC OS has rebooted, click the "Menu" (middle) button on the mouse over the Switcher icon (cog on the right of the icon bar - bottom right of screen) and the select the Configure option in the menu. # Click the Network icon in the window that appears. # Click the Internet icon in the window that appears. # Click Enable TCP/IP Protocol Suite, then click the Interfaces icon. # In 'Interfaces' make sure EtherRPCEm is selected and click the Configure... button. # Choose DHCP; and Click Set. The window closes. # Click the close option in the Interfaces window. # Click the close option in the Internet window. # Click Save in the Network window. # Click "Reset now" in the window that appears. <b>Testing</b> After the reboot press Ctrl and F12 simultaneously to reach a task window showing a command prompt. * Type <b>ifconfig -a</b><br />The response should show the rpcem0 interface has an address of 10.10.10.10 * Type <b>ping -c 1 10.10.10.2</b> to establish that the virtual router created by RPCEmu is working (the -c 1 limits to one ping packet otherwise the action continues until you press Escape). You cannot ping any IP except the virtual router (10.10.10.2) as the current NAT setup does not forward ICMP * Type <b>gethost www.google.com</b><br />The response gives the IP address of the www server at google.com domain * Type <b>gethost -t www.google.com</b><br />The response will now include the time it took for your DNS server to respond. * Type <b>gethost -x -t 8.8.8.8</b><br />The response will give the hostname (it's dns.google) of the address you typed, and the last line will be the time it took for your DNS server to respond. h3. Limitations * The emulator does not support IDE hard discs or CDROM. The OS does, but the emulator has a data loss bug. * If you do not configure the emulator to use 2MB VRAM, you may get redraw issues in the RISC OS desktop. * Restarting RISC OS will not work ("Bad PC" error) if you have less than 256MB RAM configured. Workaround: Select 256MB RAM in RPCEmu Preferences. * As stated at the top: RISC OS 5 uses the processor in 32 bit mode. Legacy 26 bit applications will first need updating, or Aemulor used for any that can't be updated. h3. Networking limitations * Using the NAT option you are hidden from your local network, so sharing of resources between the emulator and other computers on the network does not work. * The NAT setup uses one specific IP in a /24 subnet (10.10.10.0/24) - if your local network uses this same range this networking setup will not work. Change your router settings to use a different IP range. h2(#Upgrade). Upgrading from an older version of RPCEmu * Obtain the RPCEmu distribution archive "RPCEmu-0.9.4a-Release.zip":https://github.com/Septercius/rpcemu-dev/releases as mentioned above. * Delete (or move elsewhere) your existing versions of "RPCEmu-Interpreter" and "RPCEmu-Recompiler" - they are most likely to be installed in the "Applications" folder. * Install the updated versions of "RPCEmu-Interpreter" and "RPCEmu-Recompiler" in the Applications folder. * In your existing Data directory, create a "netroms" folder (alongside "hostfs", "poduleroms" and "podules"). * Copy "EtherRPCEm,ffa" from the "netroms" folder of your RPCEmu distribution archive to the "netroms" folder you just created. * Open the Applications folder, right-click on "RPCEmu-Interpreter" and choose "Open". Acknowledge the warning screen(s) that appear. * Double-click on "RPCEmu-Interpreter" to launch RPCEmu. This should load to the RISC OS desktop. * You may need to enable networking, as explained "above.":#Network * If you are using an Intel-based Mac, repeat the previous 3 steps for RPCEmu-Recompiler. After starting RPCEmu, you may discover that "mouse capture" mode is not working properly. To fix this, proceed as follows: * Go to <i>System Preferences > Security & Privacy > Privacy > Accessibility</i> and untick the entry for "RPCEmu-Interpreter". * Close the System Preferences window. * Start RPCEmu-Interpreter and untick "Follow Host Mouse" so that macOS is aware that RPCEmu wants to control the computer. * Reopen <i>System Preferences > Security & Privacy > Privacy > Accessibility</i> and tick the entry for "RPCEmu-Interpreter". * If you are using an Intel-based Mac, repeat the above process for "RPCEmu-Recompiler". h2(#Usage). Usage notes h3. Keyboard <table border="1" cellspacing="0"> <tr> <th bgcolor="silver">Key marking</th> <th bgcolor="silver">Character generated</th> </tr> <tr> <td align="center">§</td> <td align="center">`</td> </tr> <tr> <td align="center">`</td> <td align="center">\</td> </tr> <tr> <td align="center">\</td> <td align="center">#</td> </tr> <tr> <td align="center">"</td> <td align="center">@</td> </tr> <tr> <td align="center">@</td> <td align="center">"</td> </tr> </table> Go to Mac "System Preferences > Keyboard > Keyboard" and tick "Use F1, F2 etc. keys as standard function keys". Also, go to "System Preferences > Keyboard > Shortcuts" and check that you don't have anything mapped to F12. You may also need to move (or disable) some or all of Ctrl-F1 to Ctrl-F8, as they can prevent the use of the corresponding keyboard shortcuts in RISC OS. If you have an extended keyboard (with numeric keypad): * F13 is Print Screen * F14 is Scroll Lock * F15 is Break * The "X in a square" key below F16 is Num Lock. Also with the extended keyboard, move some of the Mac keyboard shortcuts so that they don't clash with RISC OS usage. A suggested layout is: <table border="1" cellspacing="0"> <tr> <th bgcolor="silver">Function</th> <th bgcolor="silver">Old shortcut</th> <th bgcolor="silver">New shortcut</th> </tr> <tr> <td>Mission Control</td> <td>F9</td> <td>F16</td> </tr> <tr> <td>Application windows</td> <td>F10</td> <td>F17</td> </tr> <tr> <td>Show desktop</td> <td>F11</td> <td>F18</td> </tr> <tr> <td>Move left a space</td> <td>Ctrl-leftarrow</td> <td>Ctrl-Opt-leftarrow</td> </tr> <tr> <td>Move right a space</td> <td>Ctrl-rightarrow</td> <td>Ctrl-Opt-rightarrow</td> </tr> </table> h3. Downloading and transferring software RISC OS uses a special format of ZIP archive: if these are unpacked under macOS, the individual files will lose their filetypes. The correct process is to copy the ZIP file into the HostFS folder inside the RPCEmu data directory and unpack it from RISC OS. Tip: Go to Safari preferences and untick "Open safe files after downloading". This will prevent macOS from unpacking the ZIP file.[1] fn1. <small>If you prefer to leave the option ticked, the ZIP file is moved to the Bin after unpacking, so can still be moved to the HostFS folder.</small> h3. Other notes * If you want to change Data directories, hold down Shift when starting RPCEmu. * To exit full-screen mode, use Ctrl-Cmd-downarrow (not Ctrl-End). * Selecting "2-button mouse" causes the CMD key to behave as MENU. * Mouse pointer stuck in window? Go to Mission Control (e.g. Fn-F3), move the mouse pointer elsewhere on the screen and click a mouse button. * UnTarBZ2 will not work if you try to decompress to HostFS. Instead, create a RAM disc large enough to hold the decompressed files and decompress there.