ARM programming for Risc OS

RISC OS was the operating system of the Acorn Archimedes... although the machine is long since dead, RISC OS has survived and ported to modern machines like the Raspberry Pi

In these tutorials we'll be testing with Risc OS 3.57 - which is the OS of the successor of the Archimedes, but where possible we'll try and support the classic RiscOS 2... and we'll be using instructions compatible with ARM2 for backwards compatibility!

These tutorials use the VASM assembler

Acorn Archimedes versions

	A3000	A5000	RISC PC
CPU	8mhz ARM2	25 mhz ARM3	30mhz ARM 610
Memory	1 MB	1-8 MB	?
OS	RISC OS 2	RISC OS 3	Risc OS 3.5 - 4.03
Screen	320x240 16/256 color	320x240 16/256 color	320x240 16/256 color

If you want to learn ARM get the Cheatsheet! it has all the ARM7 commands, it covers the commands, and options like Bitshifts and conditions as well as the bytecode structure of the commands!

Resources

RPCEMU - Risc OS emulator
Rom Images - Images for RISC OS

Executable files

The easiest way to create a program is save it as a FF8.... eg 'prog,ff8'... NOTE: this is a COMMA before ff8 not a full stop - this is how RISC OS denotes file type

Our program just needs to start from 0x8000 and it will work fine!... please note, you'll need to create your own stack area and define a stack pointer if you need the Stack, as the OS doesn't create one!

The Example Hello World to the right will compile correctly with VASM

.org 0x08000
    SWI 01                    ;OS_WriteS
    .ascii "Hello World!"
    .byte 0                   ;End of string
    .align 4

     MOV R0,#0                ;0=No Error
     SWI 0x11               ;OS_Exit

We can also create a !Run,feb to autostart the program with the emulator, we

RMEnsure UtilityModule 3.10 Error This !Boot structure is only suitable for RISC OS 3.1 or later
Set Boot$Dir <Obey$Dir>
Set Boot$Path <Boot$Dir>.
desktop prog

Using Risc OS

When using Risc OS, you will often want the options on a file... to get this use the MIDDLE MOUSE button
You can get a command prompt by pressing CTRL-F12, or selecting Task Window by middle clicking on the Acorn icon The commands you can use are known as Star Commands... there is a list of them here

256 color mode

On RiscOS, 256 color mode probably doesn't work the way you want!

Only 64 colors are configurable, Each of these are presented using 4 different brightness (defined by the bottom 2 bits.

Here is the default 256 color palette:

Bit	Meaning
0	Tint bit 0 (red + green + blue bit 0)
1	Tint bit 1 (red + green + blue bit 1)
2	Red bit 2
3	Blue bit 2
4	Red bit 3 (high)
5	Green bit 2
6	Green bit 3 (high)
7	Blue bit 3 (high)

VDU Commands

Many screen functions are performed via 'VDU Commands'... to use these, we just write special character codes to the screen with SWI 0

Page	Meaning	Parameters	Example
VDU 0	Does nothing	0
VDU 1	Sends next character to printer only	1,c
VDU 2	Enables printer	2
VDU 3	Disables printer	3
VDU 4	Writes text at text cursor	4
VDU 5	Writes text at graphics cursor	5
VDU 6	Enables VDU driver	6
VDU 7	Generates bell sound	7
VDU 8	Moves cursor back one character	8
VDU 9	Moves cursor on one space	9
VDU 10	Moves cursor down one line	10
VDU 11	Moves cursor up one line	11
VDU 12	Clears text window	12
VDU 13	Moves cursor to start of current line	13
VDU 14	Turns on paged mode	14
VDU 15	Turns off paged mode	15
VDU 16	Clears graphics window	16
VDU 17	Defines text colour	17,color
VDU 18	Defines graphics colour	18,maskmode,color
VDU 19	Defines logical colour	19,color,mode,r,g,b	19,0,16,255,128,0
VDU 20	Restores default logical colours	20
VDU 21	Disables VDU drivers	21
VDU 22	Selects screen mode	22,ScreenMode	22,9
VDU 23	Multi-purpose command:	n,n,n,n,n,n,n,n,n
VDU 23	Sets the interlace and controls cursor appearance	?
VDU 23	Controls text cursor appearance	?
VDU 23	Defines ECF pattern and colours	?
VDU 23	Sets dot-dash line style	?
VDU 23	Scrolls text window or screen	?
VDU 23	Clears a block of the text window	?
VDU 23	Sets first flash time	?
VDU 23	Sets second flash time	?
VDU 23	Sets default patterns	?
VDU 23	Defines simple ECF patterns and colours	?
VDU 23	Controls cursor movement after printing	?
VDU 23	Sets the tint for a colour	?
VDU 23	Chooses ECF patterns	?
VDU 23	Exchanges text foreground and background colours	?
VDU 23	Sets ECF origin	?
VDU 23	Sets character size/spacing	?
VDU 23	Reserved for future expansion	?
VDU 23	Private Font Manager calls	?
VDU 23	Private Sprite Manager calls	?
VDU 23	Reserved for use by application programs	?
VDU 23	Redefines printable characters	?
VDU 24	Defines graphics window	24,x1,y1,x2,y2
VDU 25	PLOT command	25,x,y
VDU 26	Restores default windows	26
VDU 27	Does nothing	27
VDU 28	Defines text window	28,x1,y1,x2,y2
VDU 29	Defines graphics origin	29,x,y
VDU 30	Homes text cursor	30
VDU 31	Moves text cursor	31,x,y
VDU 127	Delete	127

SWI commands
SWI's are systems calls to the operating system... many SWI's were added in later operating system versions, so ensure you only use SWI's that exist on the version you want to support.

OS Ver	Number	Name	Function
2	&00	OS_WriteC	Write Character R0 to Screen
2	&01	OS_WriteS	Write 0 termniated string to screen � string follows SWI in code
2	&02	OS_Write0
2	&03	OS_NewLine	Start a new line (no params)
2	&04	OS_ReadC
2	&05	OS_CLI
2	&06	OS_Byte Index of OS_Bytes
2	&07	OS_Word Index of OS_Words
2	&08	OS_File
2	&09	OS_Args
2	&0A	OS_BGet
2	&0B	OS_BPut
2	&0C	OS_GBPB
2	&0D	OS_Find
2	&0E	OS_ReadLine
2	&0F	OS_Control
2	&100-1FF	OS_WriteI
2	&10	OS_GetEnv
2	&11	OS_Exit	Return to OS� R0=Errorcode (0=no error)
2	&12	OS_SetEnv
2	&13	OS_IntOn
2	&14	OS_IntOff
2	&15	OS_CallBack
2	&16	OS_EnterOS
2	&17	OS_BreakPt
2	&18	OS_BreakCtrl
2	&19	OS_UnusedSWI
2	&1A	OS_UpdateMEMC
2	&1B	OS_SetCallBack
2	&1C	OS_Mouse
2	&1D	OS_Heap OS_Heap (5a)
2	&1E	OS_Module
2	&1F	OS_Claim
2	&20	OS_Release
2	&21	OS_ReadUnsigned
2	&22	OS_GenerateEvent
2	&23	OS_ReadVarVal
2	&24	OS_SetVarVal
2	&25	OS_GSInit
2	&26	OS_GSRead
2	&27	OS_GSTrans
2	&28	OS_BinaryToDecimal
2	&29	OS_FSControl OS_FSControl 55
2	&2A	OS_ChangeDynamicArea OS_ChangeDynamicArea (5a)
2	&2B	OS_GenerateError
2	&2C	OS_ReadEscapeState
2	&2D	OS_EvaluateExpression
2	&2E	OS_SpriteOp Changes to OS_SpriteOp OS_SpriteOp 17
2	&2F	OS_ReadPalette
2	&30	OS_ServiceCall OS_ServiceCall (5a)
2	&31	OS_ReadVduVariables	R0 = pointer to input block , R1 = pointer to output block
2	&32	OS_ReadPoint
2	&33	OS_UpCall
2	&34	OS_CallAVector
2	&35	OS_ReadModeVariable OS_ReadModeVariable (5a)
2	&36	OS_RemoveCursors	Disable Cursor (No Params)
2	&37	OS_RestoreCursors
2	&38	OS_SWINumberToString
2	&39	OS_SWINumberFromString
2	&3A	OS_ValidateAddress
2	&3B	OS_CallAfter
2	&3C	OS_CallEvery
2	&3D	OS_RemoveTickerEvent
2	&3E	OS_InstallKeyHandler
2	&3F	OS_CheckModeValid OS_CheckModeValid (5a)
2	&40	OS_ChangeEnvironment
2	&41	OS_ClaimScreenMemory
2	&42	OS_ReadMonotonicTime
2	&43	OS_SubstituteArgs
2	&44	OS_PrettyPrint
2	&45	OS_Plot OS_Plot (5a)
2	&46	OS_WriteN
2	&47	OS_AddToVector
2	&48	OS_WriteEnv
2	&49	OS_ReadArgs
2	&4A	OS_ReadRAMFsLimits
2	&4B	OS_ClaimDeviceVector
2	&4C	OS_ReleaseDeviceVector
2	&4D	OS_DelinkApplication
2	&4E	OS_RelinkApplication
2	&4F	OS_HeapSort
2	&50	OS_ExitAndDie
2	&51	OS_ReadMemMapInfo
2	&52	OS_ReadMemMapEntries
2	&53	OS_SetMemMapEntries OS_SetMemMapEntries (5a)
2	&54	OS_AddCallBack
2	&55	OS_ReadDefaultHandler
2	&56	OS_SetECFOrigin
2	&57	OS_SerialOp OS_SerialOp (5a)
2	&58	OS_ReadSysInfo OS_ReadSysInfo (5a)
2	&59	OS_Confirm
2	&5A	OS_ChangedBox
2	&5B	OS_CRC
3	&5C	OS_ReadDynamicArea OS_ReadDynamicArea (5a)
3	&5D	OS_PrintChar
3	&5E	OS_ChangeRedirection
3	&5F	OS_RemoveCallBack
3	&60	OS_FindMemMapEntries
3	&61	OS_SetColour OS_SetColour (5a)
3	&64	OS_Pointer
3.5	&65	OS_ScreenMode
3.5	&66	OS_DynamicArea
2	&68	OS_Memory
2	&69	OS_ClaimProcessorVector
3.5	&6A	OS_Reset
3.5	&6B	OS_MMUControl
2	&C0	OS_ConvertStandardDateAndTime
2	&C1	OS_ConvertDateAndTime
2	&D0	OS_ConvertHex1
2	&D1	OS_ConvertHex2
2	&D2	OS_ConvertHex3
2	&D3	OS_ConvertHex4
2	&D4	OS_ConvertHex8
2	&D5	OS_ConvertCardinal1
2	&D6	OS_ConvertCardinal2
2	&D7	OS_ConvertCardinal3
2	&D8	OS_ConvertCardinal4
2	&D9	OS_ConvertInteger1
2	&DA	OS_ConvertInteger2
2	&DB	OS_ConvertInteger3
2	&DC	OS_ConvertInteger4
2	&DD	OS_ConvertBinary1
2	&DE	OS_ConvertBinary2
2	&DF	OS_ConvertBinary3
2	&E0	OS_ConvertBinary4
2	&E1	OS_ConvertSpacedCardinal1
2	&E2	OS_ConvertSpacedCardinal2
2	&E3	OS_ConvertSpacedCardinal3
2	&E4	OS_ConvertSpacedCardinal4
2	&E5	OS_ConvertSpacedInteger1
2	&E6	OS_ConvertSpacedInteger2
2	&E7	OS_ConvertSpacedInteger3
2	&E8	OS_ConvertSpacedInteger4
2	&E9	OS_ConvertFixedNetStation
2	&EA	OS_ConvertNetStation
2	&EB	OS_ConvertFixedFileSize
2	&EC	OS_ConvertFileSize

OS_Bytes - (SWI 6)

Number	Description	R0	Options
&00	Display OS version information	0
&02	Specify input stream	2
&03	Specify output streams	3
&04	Cursor key status	4
&05	Write printer driver type	5
&06	Write printer ignore character	6
&07	Write RS423 receive rate	7
&08	Write RS423 transmit rate	8
&09	Write duration of first colour	9
&0A	Write duration of second colour	10
&0B	Write keyboard auto-repeat delay	11
&0C	Write keyboard auto-repeat rate	12
&0D	Disable event	13
&0E	Enable event	14
&0F	Flush buffer	15
&10	Store the number of channels to be sampled	16
&11	Return to the caller, doing nothing	17
&12	Reset function keys	18
&13	Wait for vertical sync (vsync)	19
&14	Reset font definitions	20
&15	Flush selected buffer	21
&19	Reset group of font definitions	25
&46	Read/write country number	70
&47	Read/write alphabet or keyboard	71
&6A	Select pointer / activate mouse	106
&70	Write VDU driver screen bank	112
&71	Write display hardware screen bank	113
&72	Write shadow/non-shadow state	114
&75	Read VDU status	117
&76	Reflect keyboard status in LEDs	118
&79	Keyboard scan	121
&7A	Keyboard scan from 16 decimal	122
&7C	Clear escape condition	124
&7D	Set escape condition	125
&7E	Acknowledge escape condition	126
&7F	Check for end of file	127
&80	Get buffer/mouse status	128
&80	Return switch state and last channel converted	128
&81	Scan a for a particular key	129	R1=Wait, R2=0.... Returns R1=Ascii R1=255^Keycode,R2=255... Returns R1=255 if pressed
&86	Read text cursor position	134
&87	Read character at text cursor and screen mode	135
&8A	Insert character code into buffer	138
&8B	Write filing system options	139
&8F	Issue module service call	143
&90	Set vertical screen shift and interlace	144
&91	Get character from buffer	145
&98	Examine buffer status	152
&99	Insert character into buffer	153
&9C	Read/write asynchronous communications state	156
&A0	Read VDU variable value	160
&A1	Read battery backed RAM	161
&A2	Write battery backed RAM	162
&A3	Read/write general graphics information	163
&A5	Read output cursor position	165
&B0	50Hz counter	176
&B1	Read input source	177
&B5	Read/write RS423 input interpretation status	181
&B6	Read/write NoIgnore state	182
&BC	Read the current channel	188
&BD	Read the number of channels to be sampled	189
&BE	Read the resolution of conversion	190
&BF	Read/write RS423 busy flag	191
&C0	Read RS423 control byte	192
&C1	Read/write flash counter	193
&C2	Read duration of second colour	194
&C3	Read duration of first colour	195
&C4	Read/write keyboard auto-repeat delay	196
&C5	Read/write keyboard auto-repeat rate	197
&C6	Read/write *Exec file handle	198
&C7	Read/write *Spool file handle	199
&C8	Read/write Break and Escape effect	200
&C9	Read/write keyboard disable flag	201
&CA	Read/write keyboard status byte	202
&CB	Read/write RS423 input buffer minimum space	203
&CC	Read/write RS423 ignore flag	204
&D3	Read/write bell channel	211
&D4	Read/write bell sound volume	212
&D5	Read/write bell frequency	213
&D6	Read/write bell duration	214
&D8	Read/write length of function key string	216
&D9	Read/write paged mode line count	217
&DA	Read/write bytes in VDU queue	218
&DB	Read/write Tab key code	219
&DC	Read/write escape character	220
&DD	Read/write interpretation of input values &C0 - &CF	221
&DE	Read/write interpretation of input values &D0 - &DF	222
&DF	Read/write interpretation of input values &E0 - &EF	223
&E0	Read/write interpretation of input values &F0 - &FF	224
&E1	Read/write function key interpretation	225
&E2	Read/write Shift function key interpretation	226
&E3	Read/write Ctrl function key interpretation	227
&E4	Read/write Ctrl Shift function key interpretation	228
&E5	Read/write Escape key status	229
&E6	Read/write escape effects	230
&EC	Read/write character destination status	236
&ED	Read/write cursor key status	237
&EE	Read/write numeric keypad interpretation	238
&F0	Read country flag	240
&F2	Read RS423 baud rates	242
&F3	Read timer switch state	243
&F5	Read printer driver type	245
&F6	Read/write printer ignore character	246
&F7	Read/write Break key actions	247
&FA	Read VDU driver screen bank number	250
&FB	Read display screen bank number	251
&FD	Read last break type	253
&FE	Set effect of Shift Ctrl on numeric keypad	254
&FF	Read/write boot option	255

Keycodes

Esc:112

F1: 113

F2: 114

F3: 115

F4: 20

F5: 116

F6: 117

F7: 22

F8: 118

F9: 119

F10:30

F11: 28

F12: 29

Print: 32

ScrlLk:31

Brk:44

`: 45

1: 48

2: 49

3: 17

4: 18

5: 19

6: 24

7: 36

8: 21

9: 38

0: 39

-: 23

=: 93

Pnd: 46

Bksp: 47

Ins: 61

Home:62

PgUp:63

NmLk: 77

/: 74

*: 91

#: 90

Tab: 96

Q: 16

W: 33

E: 34

R: 51

T: 35

Y: 68

U: 53

I: 37

O: 54

P: 55

[: 56

]: 88

\: 120

Del: 89

Copy:105

PgDown:78

7: 27

8: 42

9: 43

-: 59

Ctrl: 14

A: 65

S: 81

D: 50

F: 67

G: 83

H: 84

J: 69

K: 70

L: 86

;: 72

': 79

Retn: 73

4: 122

5: 123

6: 26

+: 58

Shift: 03

Z: 97

X: 66

C: 82

V: 99

B: 100

N: 85

M: 101

,: 102

.: 103

/: 104

Shift:06

U:57

1: 107

2: 124

3:108

Enter: 60

Caps: 64

Alt: 25

Spc: 98

Alt:28

Ctrl: 17

L:25

D:41

R:121

0:106

.:76

File Formats

RiscOS file extensions use a 3 character type, preceded by a COMMA, not a full stop, eg "prog,ff8" (PROG COMMA FF8)

Category	EXT	Type
General	FFF	Plain ASCII text	Text
	FFE	Command (Exec) file	Command
	FFD	Data	Data
	FFC	Position independent code	Utility
	FFB	Tokenised BASIC program	BASIC
	FFA	Relocatable module	Module
	FF9	Sprite or saved screen	Sprite
	FF8	Absolute application loaded at &8000	Absolute
	FF7	BBC font file (sequence of VDU operations)	BBC font
	FF6	Font	Font
	FF5	PostScript	PoScript
	FF4	Dot Matrix data file	Printout
	FF3	LaserJet data file	LaserJet
	FF2	Configuration (CMOS RAM)	Config
	FF1	Raw unprocessed data (e.g. terminal streams)	RawData
	FF0	Tagged Image File Format	TIFF
	FED	Palette data	Palette
	FEC	Template file	Template
	FEB	Obey file	Obey
	FEA	Desktop	Desktop
	FE9	ViewWord	ViewWord
	FE8	ViewPS	ViewPS
	FE7	ViewSheet	ViewSht
	FE6	UNIX executable	UNIX Ex
	FE4	DOS file	DOS
	FE3	Atari file	Atari
	FE2	Commodore Amiga file	Amiga
	FE1	Make data	Make
	FDF	TCP/IP suite	VT220 script
	FDE	TCP/IP suite	VT220 setup
	FDD	Master utilities	MasterUtl
	FDC	TCP/IP suite	unresolvable UNIX soft link
	FDB	Text using CR and LF for line ends	TextCRLF
	FDA	PC Emulator	DOS batch file
	FD9	PC Emulator	DOS executable file
	FD8	PC Emulator	DOS command file
	FD7	Obey file in a task window	TaskObey
	FD6	Exec file in a task window	TaskExec
	FD5	DOS Pict	Pict
	FD4	International MIDI Assoc. MIDIfiles standard	MIDI
	FD3	Acorn DDE	debuggable image
	FD1	BASIC stored as text	BASICTxt
	FD0	PC Emulator	configuration
	FCF	Font cache	Cache
	FCE	FileCore floppy disc image FileCoreFloppyDisc
	FCD	FileCore hard disc image	FileCoreHardDisc
	FCC	Device object within DeviceFS	Device
	FCA	Single compressed file	Squash
	FC9	Sun raster file	SunRastr
	FC8	DOS MultiFS disc image	DOSDisc
Industry standard file types	DFE	Comma separated values	CSV
	DEA	Data exchange format (AutoCAD etc)	DXF
	DB4	SuperCalc III file	SuperCalc
	DB3	DBase III file	DBaseIII
	DB2	DBase II	DBaseII
	DB1	DBase index file	DBaseIndex
	DB0	Lotus 123 file	WK1 (was Lotus123)
	CE5	TEX file	TeX
	CAF	IGES graphics	IGES
	CAE	Hewlett-Packard graphics language	HPGLPlot
	C85	JPEG (Joint Photographic Experts Group) file	JPEG
Acorn Advance file types	C25	Acorn Advance Wordprocessor	AWord
	C26	Acorn Advance Spreadsheet	ASheet
	C27	Acorn Advance Database	ADBase
	C28	Acorn Advance Graph	AGraph
BBC ROM file type	BBC	BBC ROM file (ROMFS)	BBC ROM


Acornsoft file types	AFF	Draw file	DrawFile
	AFE	Mouse event record	Mouse
	AFA	DTP style file	DtpStyle
	AF9	DTP documents	DtpDoc
	AF8	First Word Plus file	1stWord+
	AF7	Help file	HelpInfo
	AF1	Maestro file	Music
	AF0	ArcWriter file	ARCWriter
	AE9	Alarm file	Alarms
	ADB	Outline font (obsolete file type)	New Font

BASIC commands

RiscOS has a built in BBC Basic interpreter, which is also capable of assembly!

Category	Basic Command
Assembly language	CALL, SYS, USR
Character/string handling	ASC, CHR$, INSTR(, LEFT$(, LEN, MID$(, RIGHT$(, STR$, STRING$(
Error handling	ERL, ERR, ERROR, LOCAL ERROR, ON ERROR, REPORT, REPORT$, RESTORE ERROR
File commands	BGET#, BPUT#, CLOSE#, EOF#, EXT#, GET$#, INPUT#, OPENIN, OPENOUT, OPENUP, PRINT#, PTR#
Graphics	BY, CIRCLE, CLG, CLS, COLOUR (COLOR), DRAW, ELLIPSE, FILL, GCOL, LINE, MODE, MOVE, OFF, ON, ORIGIN, PLOT, POINT, POINT(, RECTANGLE, TINT, VDU, WAIT
Input/Output	GET, GET$, INKEY, INKEY$, INPUT, INPUT LINE, LINE INPUT, MOUSE, PRINT, SPC, TAB, WIDTH
Logical	AND, EOR, FALSE, NOT, OR, TRUE
Numerical	ABS, DIV, EVAL, INT, MOD, RND, SGN, SQR, SUM, SUMLEN, SWAP, VAL
Program construction	APPEND, AUTO, BASIC, BASIC64, CRUNCH, DELETE, EDIT, HELP, INSTALL, LIST, LISTO, LOAD, LVAR, NEW, OLD, RENUMBER, SAVE, TEXTLOAD, TEXTSAVE, TWIN
Program statements	CHAIN, CLEAR, DATA, DEF, DIM, END, ENDPROC, FN, GOSUB, GOTO, LET, LIBRARY, LOCAL, OSCLI, PROC, QUIT, READ, REM, RESTORE, RETURN, RUN, STOP, TRACE
Sound	BEAT, BEATS, SOUND, STEREO, TEMPO, VOICES
Structures	CASE, ELSE, ENDCASE, ENDIF, ENDWHILE, FOR, IF, NEXT, OF, OTHERWISE, REPEAT, THEN, UNTIL, WHEN, WHILE
Trigonometric	ACS, ASN, ATN, COS, DEG, EXP, LN, LOG, PI, RAD, SIN, TAN
Variables	ADVAL, COUNT, HIMEM, LOMEM, PAGE, POS, TIME, TIME$, TOP, VPOS