<!-- Forthmacs Formatter generated HTML output -->
<html>
<head>
<title>RiscOS Interface</title>
</head>
<body>
<h1>RiscOS Interface</h1>
<hr>
<p>
This chapter gives a short overview about how to use RiscOS functions within 
Risc-OS Forthmacs.  All internal functions using the filing systems, IO and 
program resources as handlers, upcalls, register usage and vectors are 
implemented according to the "Risc OS3 Programming reference manuals".  The 
delivered Forth binary as well as user developed ready-to-run applications can 
use all RiscOS functions.  There are three main ways to do this.  
<p>
<p>
<h2>The CLI</h2>
<p>
1) Using the command line interface in one of the following two ways.  
<p>
<br><code>    : do-backup</code><br>
<br><code>      p" run %.backup" "shell ;  \ pass a commandline to SWI os_cli</code><br>
<br><code>    </code><br>
<br><code>    %.backup</code><br>
<p>
Both lines mean: 
<p>
Run the file backup found in the current library.  The first way works in both, 
interprete and compile mode.  The second uses a Risc-OS Forthmacs specific 
behaviour, whenever a word is not found in the word list, RiscOS will try to 
serve you.  The rest of the line is passed as an argument to  <code><A href="_smal_AW#76"> "shell </A>.</code> 
<p>
<p>
<h2>Forthmacs words</h2>
<p>
2) The most important operating system commands are given as Risc-OS Forthmacs 
words, 
<p>

See:  <code><A href="_smal_BQ#178"> cd </A></code>  <code><A href="_smal_BF#25d"> ls </A></code>  <code><A href="_smal_AU#254"> ll </A></code>  <code><A href="_smal_AQ#1c0"> dir </A></code>  <code><A href="_smal_AD#273"> mv </A></code>  <code><A href="_smal_AJ#1b9"> delete </A></code>  <code><A href="_smal_BV#26d"> mkdir </A></code>  <code><A href="_smal_AM#2ac"> rename </A></code>  <code><A href="_smal_BM#144"> access </A></code>  <code><A href="_smal_BD#db"> .date </A></code>  <code><A href="_smal_BQ#e8"> .today </A></code>  <code><A href="_smal_BK#e2"> .now </A></code>  <code><A href="_smal_AU#1f4"> fcount </A></code>  <code><A href="_smal_BM#204"> fload </A></code>  <code><A href="_smal_AG#276"> needs </A></code>  <code><A href="_smal_BT#2fb"> to-file </A></code>  <code><A href="_smal_AA#150"> append-to-file </A></code>  <code><A href="_smal_BK#2c2"> save-forth </A></code>  <code><A href="_smal_BP#207"> fopen </A></code>  <code><A href="_smal_AT#1f3"> fclose </A></code> 
and many more.  Feel free to define your own mostly used OS "macros".  
<p>
<p>
<h2>The System Call Compiler -- syscall: </h2>
<p>
3) There are still hundreds of RiscOS functions not usable so far.  
<p>
They are called from within programs by passing parameters in registers ( r0, r1 
..  r6 ) and calling a  <code><A href="_smal_AR#41"> swi </A>.</code> The coding 
of these functions is very time-consuming (and will often contain bugs), so 
there is a tool called the <em>system call compiler</em> available as an 
extended ARM assembler macro tool.  
<p>
The subroutine calling conventions used by Forth differ from those used by the 
RiscOS system calls and by the C Compilers.  The System Call Compiler makes it 
easy to define Forth words which invoke system calls.  
<p>
It understands both the Forth and the Assembler/C calling conventions, and 
compiles a machine language sequence which will translate between the two.  The 
compiled code also converts between Forth-style packed strings and C-style 
null-terminated strings.  The current Version supports up to 4 strings to be 
converted.  
<p>
<p>
<h2>Specifying Arguments:</h2>
<p>
The arguments and return values of a system call are specified using a notation 
similar to a Forth stack diagram.  For example, the file opening system call in 
the kernel source is defined as follows: 
<br><code>    th 0d syscall: f_open           { "path "filename mode  -- &amp;file# }</code><br>
This corresponds to the C language specification: 
<br><code>    long f_open( mode, filename, path )</code><br>
<br><code>         long mode;</code><br>
<br><code>         char *filename;</code><br>
<br><code>         char *path;</code><br>
<p>
Note the reversed order of the argument list between Forth and C <em>"path "filename mode </em> 
versus <em>mode *filename *path </em> .  This is because the C compiler actually 
pushes the arguments on the stack in reverse order (*path first, then *filename, 
then mode).  
<p>
In C the calling routine writes the input arguments in the registers r0-r6 and 
calls the subroutine.  When the subroutine returns, the return values are found 
in the same ( or other as specified in the Reference Manual) registers.  
<p>
In Forth, the calling routine places the input arguments on the stack and calls 
the subroutine.  Forth expects the called subroutine to remove the input 
arguments from the stack.  The return value is found on the stack.  
<p>
<p>
<h2>syscall:</h2>
<p>
syscall: uses the following syntax 
<p>
<br><code>     hex</code><br>
<br><code>     0 syscall: sys-emit { char -- }</code><br>
<br><code>     8 syscall: f_create { 0 0 ' 0fff "filename 0b -- ?error }</code><br>
<br><code>    0c syscall: f_write  { #bytes adr file# 2 -- next-adr ' ?error }</code><br>
<p>
 <code><A href="_smal_BF#2ed"> syscall: </A></code> ( #n -- ) <em>name </em> { 
parameter-list -- result-list } 
<p>
 <code><A href="_smal_BF#2ed"> syscall: </A></code> defines a code definition <em>name</em> 
calling swix #n.  The words between the brackets are symbolic names for 
parameters and results that are popped from or pushed to the forth stack.  The 
symbolic names do not have any meaning at all, they can be chosen freely, only 
the first character of each parameter/result has a meaning, it defines the type 
of parameter.  
<p>
The parameters start with the opening bracket "{" , there can be up to 6 
arguments, and ends with the separator "-".  The symbolic results list ( again 
up to six results ) ends with the closing bracket "}".  
<p>
Arguments are taken from the stack, the rightmost parameter (top of stack) is 
copied to r0, the second of stack to r1, ...  
<p>
After calling the  <code><A href="_smal_AR#41"> swi </A></code> the registers 
are written back to the stack, the rightmost result comes from r0 and will be 
the top of stack ...  
<p>
To make programmer's life more easy, the system-call compiler knows some special 
cases which are recognised from the first character of the symbol-name.  
<p>
<p>
<h2>Numbers</h2>
<p>
a) If the parameter name can be converted to a number, this number is moved to 
the register instead of being popped from the stack.  This means you don't have 
to push literals to the stack first and just do a silly pop afterwards.  So you 
could define a function  <code><A href="_smal_AK#15a"> beep </A></code> like 
this 
<br><code>    0 syscall: beep  { 7 -- }</code><br>
Literals are not allowed in the result list or could you imagine a reason.  
<p>
<p>
<h2>"xyz</h2>
<p>
b) Parameters starting with a <strong>"</strong> are strings.  Before calling 
the  <code><A href="_smal_AR#41"> swi </A></code> they are converted to c-style 
0-terminated strings.  The original strings are not changed by this, they are 
copied to a string buffer.  Up to 4 strings can be used in one RiscOS call 
because of string manager limitations.  
<p>
<p>
<h2>\xyz</h2>
<p>
c) This is a dummy, the stack argument is simply "dropped" and forgotten 
forever.  The register is filled with the next top stack item.  This sometimes 
saves stack operations before calling the Risc OS functions.  
<p>
<p>
<h2>'xyz</h2>
<p>
d) This is another sort of dummy, it means that the corresponding register won't 
be loaded from the stack.  Many  <code><A href="_smal_AR#41"> swi </A></code> 
neglect some registers and so you don't have to define a dummy literal on the 
forth stack.  In the result list this allows to "forget" all results not 
interesting.  Have a look at the following definitions: 
<br><code>    9 syscall: end-of-file?     { file-descriptor 5 -- flag ' ' }</code><br>
<br><code>    8 syscall: f_access         { protection ' ' ' "filename 4 -- ?error }</code><br>
The first function returns a flag in r2, this is directly copied to the 
top-of-stack, r0 and r1 are not used at all.  The second function needs a 
"protection" in r5 ( protection ) r4, r3 and r2 are not needed and therefore get 
a dummy ' , r1 is a string and will be converted because of the leading  <code><A href="_smal_AP#6f"> ". </A></code> 
The function needs a literal 4 in r0.  The ?error in the result list produces a 
flag.  
<p>
So the stack comments would be: 
<br><code>    end-of-file?    ( fd -- flag )</code><br>
<br><code>    f_access        ( protection str -- flag )</code><br>
<p>
<p>
<h2>?xyz</h2>
<p>
As you will be able to imagine from the f_access function ? produces a flag.  If 
the  <code><A href="_smal_AR#41"> swi </A></code> returns with the V-flag set 
the flag will be true, otherwise false.  Also the according register is written 
to  <code><A href="_smal_AH#1e7"> errno </A>.</code> 
<p>
<p>
<h2>&amp;xyz</h2>
<p>
If an error has occurred in  <code><A href="_smal_AR#41"> swi </A></code> ( 
V-flag is set ) leave  <code><A href="_smal_AE#304"> true </A></code> and set  <code><A href="_smal_AH#1e7"> errno </A>,</code> 
otherwise leave the corresponding register/stack unchanged.  Look at this 
<br><code>    0d syscall: f_open  { "path "filename mode  -- &amp;file# }</code><br>
f_open returns a file handle or  <code><A href="_smal_AE#304"> true </A></code> 
as an error indicator.  
<p>
The closing bracket must be there for error control.  To find out more about 
this tool you could have a look at the <em>risc_os.syskern </em> file and see 
what is compiled.  Try to define your own function calls using the "Programming 
Reference Manuals".  
<p>
<p>
<h2>Books</h2>
<p>
For writing the best possible code using RiscOS and ARM processors I strongly 
recommend two books (probably you won't need any others): 
<p>
RISC OS 3 Programmer's Reference Manual, Acorn Computers Ltd.  
ISBN-1-85250-110-3 
<p>
Acorn Risc Machine Family Data Manual, Prentice Hall, ISBN-0-13-781618-9 
<p>
</body>
</html>
