Tutorial 00 - Getting started

From ARMwiki
(Difference between revisions)
Jump to: navigation, search
m (Tweak for clarity.)
m (Tutorial00 moved to Tutorial 00 - Getting started: Title now describes the content.)

Latest revision as of 05:56, 7 March 2012


[edit] Getting started

Before we begin, we need to have a level playing field. Now the problem is that there are all sorts of ARM development platforms, but there is no common factor in them, and in some cases playing with ARM code is tedious. For example, I can run arm-linux-gcc on my x86 computer to compile code to copy to my ARM based PVR to run... but what a load of bother.

Therefore, the tutorials will be based upon RISC OS.

The benefits of RISC OS are as follows:

  • Suitable emulators exist for Windows, Mac, and Linux machines. Sources too, if you have some esoteric box and fancy porting.
  • RISC OS is an ARM based operating system. Once you are in RISC OS, you are in ARM land.
  • Running ARM code is as simple as assembling and running it, right there!
  • RISC OS offers many system calls to make programming fun!
  • Trust me, I can get you to the point of running your first ARM code program in under five minutes. Just have a Windows PC with at least a 1.6GHz processor handy.


[edit] Your RISC OS computer

Now the best way to delve into RISC OS is to pick up a RiscPC from eBay. Or maybe an A7000 or 7000+. You can't beat running ARM on real ARM.
As I write this page, there's a StrongARM RiscPC currently up for 99p though I'm sure that'll go up a fair bit at the end of the auction time.

The next best idea is a commercial emulator. This is Virtual Acorn which offers a good solid emulation platform for Windows and Mac. It comes complete with an operating system ROM image, start-up files, etc. This is plug'n'play stuff.

The final idea is the freebie. A free emulator and a free operating system to run on it. The emulator isn't as polished as VirtualAcorn, and the OS version is "bleeding edge" so may be a bit quirky, however, it'll cost you nothing.
It can't hurt to try this - and if you are interested in what you see, Virtual Acorn is currently selling their RiscPC emulator for £49...

[edit] Here we go!

Okay, I promised you five minutes (or less) to get your first ARM program running. You give me a decent spec Windows box with broadband of some form as your workstation, and I'll give you RISC OS.


[edit] The emulator

First, grab yourself a copy of RPCEmuSpoon (yes, seriously, it is called that!). The files are here and I recommend the .msi installer file - just download it and then run it to install the emulator.

Do not run the emulator!

  • If you have a Mac or Linux box, there are options here for those machines, however you're on your own in these cases - I'm not particularly familiar with Linux and I know zip about Macs.

[edit] RISC OS

Because of copyright issues, while the most useful version of RISC OS is likely to be 3.70 (or 3.71), such ROM images are not lawfully available. You can find them, and, God help us, there's probably even Rule 34 too if you look far enough. You're on your own if you want to run an unlawful copy of somebody's ROMs...

However, there is in existence a bleeding edge port of RISC OS 5 for the older IOMD class machines. What this means in non-gobbledegook is there's a ROM image of the open source RISC OS 5 that will run on the emulator you just installed. Download it now!

[edit] Install the ROM image

The ROM image is a zip archive. Open it using the tool of your choice, be it WinZip or 7Zip or even XP's built in effort. You will see a 4MiB file called "riscos".

Click XP's Start button, go to All programs and then RPCEmu and click on the option Shortcut to RPCEmu Directory. Explorer will open showing RPCEmu's files and resources.

Open the "roms" subfolder.

Copy the "riscos" file from the archive into this roms folder.

You can now close the Explorer window, but take a moment to ponder that the entirety of RISC OS is a mere 4MiB.

[edit] Running the emulator

Click XP's Start button, go to All programs and then RPCEmu and click on the option RPCEmu Interpreter.

  • The interpreter is slightly slower then the recompiler, however you may find that the recompiler version gives DEP faults, which Windows will fault and abort the program. You can add RPCemu to the list of DEP exceptions, for what DEP does is to trap unusual code sequences (such as self-modifying code) which are often problems, but in something like a recompiling emulator is actually how it works.

Switching off DEP is beyond the scope of this document, so for now if you don't know how, I would suggest you stick with the interpreter version of PRCemu.

The emulator will start up, and immediately throw an error. This is not a surprise, for the machine hasn't been configured yet. Just click the Cancel button.

Tutorial starterror.png

You'll see a logo appear briefly saying it's an Iyonix (ho ho) and then... well... that's it. RISC OS is pretty quick to boot. Even with the complex boot structure (which you don't have), it wipes the floor with Linux, Windows, even mobile phones take longer to start up than RISC OS.

[edit] A few quick tweaks

Don't worry about what is happening, just do exactly what I say.

  • Click in the emulator window to give it focus.
  • Press the F12 key. This will give you a command line where everything is prefixed with a '*'. This '*' is like the DOS '>' prompt.
  • Type in the following commands, pressing Enter at the end of each line:
  Configure CDROMDrives 0
  Configure FileSystem HostFS
  Configure NoBoot
  • Now go to the top of the emulator window, click the File menu, then click Reset, and wait nine seconds (eeePC 901) while the emulator resets itself.

[edit] A crash course to RISC OS

You will be looking at this:

Tutorial desktop.png

The lower part of the screen is called the icon bar. Tasks and filesystems live here. Filesystems start on the left, towards the middle, and applications start on the right towards the middle. If the icon bar fills up, it can scroll side to side if you let your mouse pointer linger over the end you wish to scroll.

In a polar opposite to Linux and its single "/" with mount points, RISC OS takes the approach of every filing system and every partition being a separate entity. This is akin to C: and D: and E: being different, only the power and flexibility make this arrangement quite workable.

Provided on the left is "HostFS", a fake filing system that gives access to files on your harddisc (the "hostfs" folder inside RPCEmu).
To the right of that is the "Apps" repository. Long before people associated the word "Apps" with mobile phones, in fact before mobile phones even existed, RISC OS offered a special location for priveliged applications. RISC OS comes with six applications built in - an alarm clock (I wrote my own clone of this for Windows), a Character Map, a vector drawing program, a basic text editor, a help message viewer, and a bitmap painting program.

On the right, the blue egg thing hides the TaskManager to end all task managers. Seriously, Windows users should look at this and weep.
To the left of that is the DisplayManager. As you have not informed RISC OS what sort of display device you have, you are locked to a 256 colour VGA display (a safe 'default').

[edit] Your first assembler program!

  • Click once on the Apps icon on the iconbar.
  • In the window that opens, double-click on !Edit. The "!" prefix tells you that this is an application. It is actually a folder containing a bunch of stuff, then when double-clicked, is executed as an application.
  • Notice that no window appeared. Unlike Windows, a loaded application that isn't actually asked to display something will load and sit quietly on the iconbar until required. You'll see the Edit icon has appeared down the bottom to the left of DisplayManager.
  • On the Edit icon on the iconbar, press the Menu key on your keyboard. You probably haven't used this much - it's the one with a weird menu glyph to the right of the AltGr key. It's a pain to have to use the keyboard in this way, however RISC OS machines use a three-button mouse, a behaviour that isn't so well supported under Windows (even if your mouse has three buttons!).
  • Notice a menu pops up. Unlike pretty much every other operating system, RISC OS doesn't waste screen space with a permanent menu bar along the top of the window. It is all based around context-sensitive pop-up menus.
  • The second option down is Create. Put your mouse pointer on that, and move towards the arrow on the right. A submenu will appear.
  • Choose BASIC.
Tutorial selbasic.png
  • A blank window titled "<untitled>" appears.
  • Press the F3 key.
  • A save dialogue saying "BASICfile" will appear. Delete that and in its place write "$.tutorial00" and then click OK.
  • Now into the window, type the following:
  DIM code% 64
  FOR loop% = 0 TO 3 STEP 3
    P% = code%
    [ OPT loop%
      ADR   R0, message
      SWI   "OS_Write0"
      MOV   PC, LR
      EQUS  "Awesome! My first assembler program! :-)"
      EQUB  10
      EQUB  0
  CALL code%
  • Press F3 and then Enter to save the file.
Tutorial firstcode.png
  • Click on the HostFS icon. A window will appear listing two objects - Network and tutorial00.
  • Double-click on tutorial00. Your code will be assembled, and then executed. It will look like this:
Tutorial firstexec.png

There you go. It might not look like much, but it's an ARM program!

[edit] Where to go from here?

I recommend you open Apps and double-click !Help. If you let your mouse linger over stuff, help messages will pop up. Familiarise yourself with what RISC OS looks like. There is a nice tutorial, or you might like to keep your eye on eBay for the RISC OS User Guide. 3.5 better than 3, but... It'll be a little outdated, but the principles are the same.

If you wish, you can expand your system to have bells and whistles. Keep on reading...

[edit] Bringing up a full system (optional)

As supplied, RISC OS is installed, operational, but is missing many of the niceties. This next step is optional, but will make your RISC OS experience quite a bit more pleasurable.

[edit] Prerequisite

The very first thing to do is to switch your emulator to run a StrongARM processor. This is important.
With the emulator running, open the Settings menu and click on Configure....
You will see the following window:

Tutorial 00 emuconfig.png

Simply alter the processor type to StrongARM. Leave the VRAM at 2Mb, and the system memory - this isn't Windows so 32Mb or more will be plenty. I've opted for 64Mb.

Click on OK and then close down the emulator.

[edit] Obtaining the resources

The next step is to get the stuff you will require, namely:

Save this file into the "hostfs" folder within RPCemu, as shown (note that armwiki and everything.zip shown here are something else):

Tutorial 00 emufiles.png

[edit] Changing the 'type' of a file

Now restart your emulator and click on the HostFS icon. A directory viewer will open, listing the files (ignore the "armwiki" directory and "everything/zip" file).

Tutorial 00 emufilesro.png

You cannot use the HardDisc4/util file yet. Unlike Windows and Unix, RISC OS does not use extensions to define the 'type' of a file. Instead the directory index (which holds metadata such as the file creation date and access permissions) contains a "file type". Therefore, in order to extract the harddisc contents from the self-extracting program, we need to tell RISC OS that it is indeed a program.

To do this, move the mouse pointer over the "HardDisc4/util" file and call up the menu. The menu is opened either with the middle mouse button, sometimes pressing both left and right mouse buttons together (though I find that doesn't tend to work very well), or by pressing the Menu key - this is usually to the right of the AltGr key (to the right of the Space Bar).

Move the mouse pointer down to the menu entry "File 'HardDisc4/util >" and move towards the little arrow on the right. A submenu will open. Go down to the "Set type >" entry and, likewise, to the arrow on the right.
A sort of submenu will open. It will say "Text" followed by a red caret. Press Backspace a few times to delete this, then type Utility and press Enter.

Tutorial 00 emuftype.png

You will notice now that the "HardDisc4/util" icon in the directory viewer has changed to be a green cog-wheel-spanner thing that says "Utility" in tiny letters.

By way of comparison with a similar operation on Windows, what we have done is to take an executable incorrectly marked as a '.txt' file and renamed it to '.com' where it can then be executed as a program.

[edit] Installing the resources

Double-click on the "HardDisc4/util" file. A blue hourglass will appear, counting up from 1 to 99 (it'll skip from 01% to 30%). This took eight minutes on my eeePC, so may I suggest now as an ideal time to make a nice cup of tea?

You will be left with a new directory called "HardDisc4" which contains lots of stuff. Double-click this directory to open it. Ignore the error message that pops up.

Press and hold the left mouse button in the upper left of the subdirectory viewer (not over a file) and then drag out the dashed banding to contain all of the files, as shown:

Tutorial 00 emudraggy.png

When you let go of the mouse button, the files will turn darker (to mean selected).

With the Shift key held down, click-drag the files from the subdirectory into the other (root) directory.
Shift-drag will move the files. It is a lot quicker than copying them.

[edit] Making the system bootable

Press Control and F12 to open a Task Window. This is the command line in a window. You will see there is a star character. This is the system command prompt. Type the following to set the machine up for booting (it is a habit to prefix star commands with a star, however at the system prompt, you don't actually need to type the star again... though it won't hurt if you do).

  *Configure Boot
  *Configure FileSystem HostFS
  *Configure Drive 4

Now press Control and Shift and F12 - the instruction for RISC OS to shut down. You will be prompted about "1 file modified" (the contents of the Task Window). You can safely Discard.

Once RISC OS has shut down (a single switch-off-or-restart prompt in the middle of the screen), you can close the emulator.

  • You should get into the habit of closing down RISC OS correctly, in this manner.

[edit] Fire up the Quattro!

It was pretty exciting to start up the open source RISC OS, wasn't it? Well, here's the next level - the complete RISC OS experience. That isn't to say that the RISC OS is otherwise incomplete, however lots of additional resources have been added to make the system even nicer. Well, you've just put in the basic set, so let's give it a spin!

Start the emulator.

You'll see it starts up with some messages on-screen (that's okay, it's normal), then goes into the desktop a little more slowly and arrives at a fancy textured-looking backdrop. Believe me, behind the scenes a lot more than just "marbled effect backdrop" has been going on.

  • If your emulator fails to start, and at the "Iyonix" logo either appears to have frozen (interpreter) or throws non-stop errors that looks like "oflaoflaoflaofla" (recompiler), please re-read the section above on Prerequisites. You must specify a StrongARM processor.

If you wish to configure the machine, click on HostFS at the bottom left, then in the directory viewer, double-click on the !Boot directory.

Tutorial 00 emupretty.png

[edit] RISC OS crash course

Applications (read carefully, it is very different to Windows):

  • Applications can either be loaded manually, or by 'running' an associated file. If the application is loaded by double-clicking a file, the application will load and the file will appear.
  • If the application is loaded by itself, it will install itself on the icon bar. It will not open a blank document window.
  • To open a blank document window, click the icon on the icon bar.
  • Closing all of an application's windows will not exit the application. You must call up the menu available by clicking on the icon on the icon bar and selecting Quit.

The icon bar:

  • The bar along the bottom of the screen is the icon bar.
  • Filing systems go on the left, applications go on the right (both working towards the centre).
  • By default, on the left is the HostFS filing system (leftmost) and the built-in "Apps" respository.
  • On the right is the screen display adjustment (the video display icon) for RISC OS has always been flexible and dynamic in its approach to display quality. The blue lozenge on the far right is the Task Manager. From here you can examine the complete and total memory allocation of RISC OS. Unlike Windows, there is no "private delta" or "virtually mapped size" or any of that rubbish. If an application claims it is using 28K, it is using 28K. It might have an associated dynamic area (but in reality this is usually only stuff like web browsers) otherwise, what you see is what is.


  • Windows are closed by clicking the 'X' icon to the left of the window title.
  • The icon to the left of the 'X' (looks like a box on top of a box) is for pushing your window to the back of the window stack.
  • You may discover that RISC OS does not bring a window to the top of the stack when you click on it (click on the title bar if that is what you want), and furthermore the active window accepting input does not need to be the topmost window (when you're used to this, the Windows method seems retarded).
  • The icon to the right of the title bar (arrow-like thing) "maximises" the window. Sometimes it isn't always what you expect as under RISC OS, Windows can have a bounding that is not "fill the screen".
  • The icon to the lower right of the window (looks like a mini game of Tetris) is for resizing the window. Hold and drag.
  • Scrollbars don't appear and disappear like on Windows. If there is nothing to scroll, they won't work. Generally a scrollbar will adjust its size as a reflection of your place in the object you're looking at. The notable exception is !Edit which does do this, only it uses some rather peculiar logic leading to an empty window with sort-of half size scroll bars.
  • Clicking a scroll bar with the right mouse button will permit a two-dimensional movement.
  • There are no menus across the top of RISC OS menus. It is entirely context-sensitive.


  • The RISC OS mouse has three buttons, labelled Select (left), Menu (centre) and Adjust (right).
  • Select is the main button. It does stuff.
  • Adjust either modifies a selection (for example the filer uses it to modify selected files) or performs the opposite action to Select (useful in a drawing program).
  • Because of the degree of context-sensitivity of RISC OS, there is a specific mouse button for calling up menus. It's the centre one, called, obviously enough, Menu.
  • Windows support for three button mice is rather lacklustre at best. You might find tapping the menu key on the Windows style keyboard is the simplest method, if a little non-intuitive.
  • It might be worth stopping and just opening menus all over the screen to see how it works.

Command line:

  • Pressing F12 will get you a single-tasking command line - the entire screen will move up and the commands will appear below in old-style VDU format.
  • Pressing ^F12 (the '^' means Control) will open a Task Window so you can enter commands in a multitasking way.


  • The RISC OS filesystem is the polar opposite to Linux (where everything hangs off the root directory '/', for example "/sdcard" and "/cdrom" and "/bin" can refer to paths on three different pieces of hardware).
  • Under RISC OS, a filing system carries a name (ADFS, IDEFS, SCSIFS, IZipFS, CDROMFS, NetFS, HostFS...) and under that name, partitions carry a name too, so ADFS::Anya.$ refers to the ADFS drive "Anya", while IDEFS::Willow.$" refers to the drive (or partition) called "Willow" under IDEFS. This might seem a bit inflexible, however RISC OS's command line parsing and path variables make it a fairly pleasant system.
  • A dollar marks the root directory. Directories are separated with full stops. Thus the Windows path "\some\folder\name" would look like "$.some.folder.name".
  • Other punctuation (#, %, ^, etc) has meaning, but these are beyond the scope of this article.
  • Any folder beginning with '!' is an application. This means RISC OS expects certain files to be present. One of which is an !Run file, which will be executed when the application begins.
  • Yes - applications are mostly self contained. Shared resources may be placed in !System, user choices will go into the choices folder, but pretty much applications are self contained.
Tutorial 00 emutaskman.png

[edit] Programmer's editor? Assembler/linker?

I am working on this. Unfortunately, the system running in a 32 bit mode (as opposed to the older RISC OS 26 bit mode) means that a number of things plain don't work. One example is !Zap. I managed to piece together a mostly working copy (the everything/zip file is part of this), however the instructions on doing so would double the size of this document, so it's hardly a suitable solution. More to follow, and if you look online for how to install stuff on the Iyonix, it'll probably work here too.

Personal tools