home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / forthmacs / htmldocs / !Forthmacs / docs / html / ROsystem < prev    next >
Encoding:
Text File  |  1996-02-23  |  9.9 KB  |  209 lines
  1. <!-- Forthmacs Formatter generated HTML output -->
  2. <html>
  3. <head>
  4. <title>RiscOS Interface</title>
  5. </head>
  6. <body>
  7. <h1>RiscOS Interface</h1>
  8. <hr>
  9. <p>
  10. This chapter gives a short overview about how to use RiscOS functions within 
  11. Risc-OS Forthmacs.  All internal functions using the filing systems, IO and 
  12. program resources as handlers, upcalls, register usage and vectors are 
  13. implemented according to the "Risc OS3 Programming reference manuals".  The 
  14. delivered Forth binary as well as user developed ready-to-run applications can 
  15. use all RiscOS functions.  There are three main ways to do this.  
  16. <p>
  17. <p>
  18. <h2>The CLI</h2>
  19. <p>
  20. 1) Using the command line interface in one of the following two ways.  
  21. <p>
  22. <br><code>    : do-backup</code><br>
  23. <br><code>      p" run %.backup" "shell ;  \ pass a commandline to SWI os_cli</code><br>
  24. <br><code>    </code><br>
  25. <br><code>    %.backup</code><br>
  26. <p>
  27. Both lines mean: 
  28. <p>
  29. Run the file backup found in the current library.  The first way works in both, 
  30. interprete and compile mode.  The second uses a Risc-OS Forthmacs specific 
  31. behaviour, whenever a word is not found in the word list, RiscOS will try to 
  32. serve you.  The rest of the line is passed as an argument to  <code><A href="_smal_AW#76"> "shell </A>.</code> 
  33. <p>
  34. <p>
  35. <h2>Forthmacs words</h2>
  36. <p>
  37. 2) The most important operating system commands are given as Risc-OS Forthmacs 
  38. words, 
  39. <p>
  40.  
  41. 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> 
  42. and many more.  Feel free to define your own mostly used OS "macros".  
  43. <p>
  44. <p>
  45. <h2>The System Call Compiler -- syscall: </h2>
  46. <p>
  47. 3) There are still hundreds of RiscOS functions not usable so far.  
  48. <p>
  49. They are called from within programs by passing parameters in registers ( r0, r1 
  50. ..  r6 ) and calling a  <code><A href="_smal_AR#41"> swi </A>.</code> The coding 
  51. of these functions is very time-consuming (and will often contain bugs), so 
  52. there is a tool called the <em>system call compiler</em> available as an 
  53. extended ARM assembler macro tool.  
  54. <p>
  55. The subroutine calling conventions used by Forth differ from those used by the 
  56. RiscOS system calls and by the C Compilers.  The System Call Compiler makes it 
  57. easy to define Forth words which invoke system calls.  
  58. <p>
  59. It understands both the Forth and the Assembler/C calling conventions, and 
  60. compiles a machine language sequence which will translate between the two.  The 
  61. compiled code also converts between Forth-style packed strings and C-style 
  62. null-terminated strings.  The current Version supports up to 4 strings to be 
  63. converted.  
  64. <p>
  65. <p>
  66. <h2>Specifying Arguments:</h2>
  67. <p>
  68. The arguments and return values of a system call are specified using a notation 
  69. similar to a Forth stack diagram.  For example, the file opening system call in 
  70. the kernel source is defined as follows: 
  71. <br><code>    th 0d syscall: f_open           { "path "filename mode  -- &file# }</code><br>
  72. This corresponds to the C language specification: 
  73. <br><code>    long f_open( mode, filename, path )</code><br>
  74. <br><code>         long mode;</code><br>
  75. <br><code>         char *filename;</code><br>
  76. <br><code>         char *path;</code><br>
  77. <p>
  78. Note the reversed order of the argument list between Forth and C <em>"path "filename mode </em> 
  79. versus <em>mode *filename *path </em> .  This is because the C compiler actually 
  80. pushes the arguments on the stack in reverse order (*path first, then *filename, 
  81. then mode).  
  82. <p>
  83. In C the calling routine writes the input arguments in the registers r0-r6 and 
  84. calls the subroutine.  When the subroutine returns, the return values are found 
  85. in the same ( or other as specified in the Reference Manual) registers.  
  86. <p>
  87. In Forth, the calling routine places the input arguments on the stack and calls 
  88. the subroutine.  Forth expects the called subroutine to remove the input 
  89. arguments from the stack.  The return value is found on the stack.  
  90. <p>
  91. <p>
  92. <h2>syscall:</h2>
  93. <p>
  94. syscall: uses the following syntax 
  95. <p>
  96. <br><code>     hex</code><br>
  97. <br><code>     0 syscall: sys-emit { char -- }</code><br>
  98. <br><code>     8 syscall: f_create { 0 0 ' 0fff "filename 0b -- ?error }</code><br>
  99. <br><code>    0c syscall: f_write  { #bytes adr file# 2 -- next-adr ' ?error }</code><br>
  100. <p>
  101.  <code><A href="_smal_BF#2ed"> syscall: </A></code> ( #n -- ) <em>name </em> { 
  102. parameter-list -- result-list } 
  103. <p>
  104.  <code><A href="_smal_BF#2ed"> syscall: </A></code> defines a code definition <em>name</em> 
  105. calling swix #n.  The words between the brackets are symbolic names for 
  106. parameters and results that are popped from or pushed to the forth stack.  The 
  107. symbolic names do not have any meaning at all, they can be chosen freely, only 
  108. the first character of each parameter/result has a meaning, it defines the type 
  109. of parameter.  
  110. <p>
  111. The parameters start with the opening bracket "{" , there can be up to 6 
  112. arguments, and ends with the separator "-".  The symbolic results list ( again 
  113. up to six results ) ends with the closing bracket "}".  
  114. <p>
  115. Arguments are taken from the stack, the rightmost parameter (top of stack) is 
  116. copied to r0, the second of stack to r1, ...  
  117. <p>
  118. After calling the  <code><A href="_smal_AR#41"> swi </A></code> the registers 
  119. are written back to the stack, the rightmost result comes from r0 and will be 
  120. the top of stack ...  
  121. <p>
  122. To make programmer's life more easy, the system-call compiler knows some special 
  123. cases which are recognised from the first character of the symbol-name.  
  124. <p>
  125. <p>
  126. <h2>Numbers</h2>
  127. <p>
  128. a) If the parameter name can be converted to a number, this number is moved to 
  129. the register instead of being popped from the stack.  This means you don't have 
  130. to push literals to the stack first and just do a silly pop afterwards.  So you 
  131. could define a function  <code><A href="_smal_AK#15a"> beep </A></code> like 
  132. this 
  133. <br><code>    0 syscall: beep  { 7 -- }</code><br>
  134. Literals are not allowed in the result list or could you imagine a reason.  
  135. <p>
  136. <p>
  137. <h2>"xyz</h2>
  138. <p>
  139. b) Parameters starting with a <strong>"</strong> are strings.  Before calling 
  140. the  <code><A href="_smal_AR#41"> swi </A></code> they are converted to c-style 
  141. 0-terminated strings.  The original strings are not changed by this, they are 
  142. copied to a string buffer.  Up to 4 strings can be used in one RiscOS call 
  143. because of string manager limitations.  
  144. <p>
  145. <p>
  146. <h2>\xyz</h2>
  147. <p>
  148. c) This is a dummy, the stack argument is simply "dropped" and forgotten 
  149. forever.  The register is filled with the next top stack item.  This sometimes 
  150. saves stack operations before calling the Risc OS functions.  
  151. <p>
  152. <p>
  153. <h2>'xyz</h2>
  154. <p>
  155. d) This is another sort of dummy, it means that the corresponding register won't 
  156. be loaded from the stack.  Many  <code><A href="_smal_AR#41"> swi </A></code> 
  157. neglect some registers and so you don't have to define a dummy literal on the 
  158. forth stack.  In the result list this allows to "forget" all results not 
  159. interesting.  Have a look at the following definitions: 
  160. <br><code>    9 syscall: end-of-file?     { file-descriptor 5 -- flag ' ' }</code><br>
  161. <br><code>    8 syscall: f_access         { protection ' ' ' "filename 4 -- ?error }</code><br>
  162. The first function returns a flag in r2, this is directly copied to the 
  163. top-of-stack, r0 and r1 are not used at all.  The second function needs a 
  164. "protection" in r5 ( protection ) r4, r3 and r2 are not needed and therefore get 
  165. a dummy ' , r1 is a string and will be converted because of the leading  <code><A href="_smal_AP#6f"> ". </A></code> 
  166. The function needs a literal 4 in r0.  The ?error in the result list produces a 
  167. flag.  
  168. <p>
  169. So the stack comments would be: 
  170. <br><code>    end-of-file?    ( fd -- flag )</code><br>
  171. <br><code>    f_access        ( protection str -- flag )</code><br>
  172. <p>
  173. <p>
  174. <h2>?xyz</h2>
  175. <p>
  176. As you will be able to imagine from the f_access function ? produces a flag.  If 
  177. the  <code><A href="_smal_AR#41"> swi </A></code> returns with the V-flag set 
  178. the flag will be true, otherwise false.  Also the according register is written 
  179. to  <code><A href="_smal_AH#1e7"> errno </A>.</code> 
  180. <p>
  181. <p>
  182. <h2>&xyz</h2>
  183. <p>
  184. If an error has occurred in  <code><A href="_smal_AR#41"> swi </A></code> ( 
  185. 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> 
  186. otherwise leave the corresponding register/stack unchanged.  Look at this 
  187. <br><code>    0d syscall: f_open  { "path "filename mode  -- &file# }</code><br>
  188. f_open returns a file handle or  <code><A href="_smal_AE#304"> true </A></code> 
  189. as an error indicator.  
  190. <p>
  191. The closing bracket must be there for error control.  To find out more about 
  192. this tool you could have a look at the <em>risc_os.syskern </em> file and see 
  193. what is compiled.  Try to define your own function calls using the "Programming 
  194. Reference Manuals".  
  195. <p>
  196. <p>
  197. <h2>Books</h2>
  198. <p>
  199. For writing the best possible code using RiscOS and ARM processors I strongly 
  200. recommend two books (probably you won't need any others): 
  201. <p>
  202. RISC OS 3 Programmer's Reference Manual, Acorn Computers Ltd.  
  203. ISBN-1-85250-110-3 
  204. <p>
  205. Acorn Risc Machine Family Data Manual, Prentice Hall, ISBN-0-13-781618-9 
  206. <p>
  207. </body>
  208. </html>
  209.