home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsm / psionics / SysCalls.1 < prev    next >
Text File  |  1994-10-25  |  35KB  |  1,050 lines
  1. PSIONICS FILE - SYSCALLS.1
  2. ==========================
  3. System calls (part 1)
  4. Last modified 1994-09-06
  5. ========================
  6.  
  7. The Psion System 3 operating system offers a large number of system calls.
  8.  
  9. A system call is identified by either a "function number" or by a "function
  10. number and a "subfunction number". These are abbreviated to "Fn" and "Sub"
  11. in the descriptions of system calls.
  12.  
  13. Each call can take up to 5 word parameters, called BX, CX, DX, SI, and DI.
  14. In addition, there may be up to two byte parameters (AH and AL) or an
  15. additional word parameter (AX). The values returned from the call have the
  16. same structure; in addition, there is an error flag and three result flags
  17. (the latter are only used by a few system calls). Note that AX is equivalent
  18. to (AH * 256 + AL); the description will use whichever is most convenient.
  19.  
  20. There are two OPL keywords for making system calls: CALL and OS. They access
  21. the same system calls, and differ only in the way in which the parameters are
  22. passed and the results returned.
  23.  
  24. The CALL keyword takes from 1 to 6 arguments. If an argument is omitted, the
  25. corresponding parameter is set to an undefined value. The first argument
  26. should be one of:
  27.     Fn
  28.     Fn + 256 * Sub
  29.     Fn + 256 * AH
  30. according to the specific system call. The remaining arguments provide the
  31. word parameters:
  32.     argument 2: BX
  33.     argument 3: CX
  34.     argument 4: DX
  35.     argument 5: SI
  36.     argument 6: DI
  37. The keyword returns a value, which is one of the results:
  38.     AX
  39.     AH * 256 + AL
  40. (which are equivalent). The flags and the other 5 results are not available.
  41.  
  42. OS takes two or three arguments; if there is no third, it is taken to be
  43. identical to the second. The first argument is Fn, while the second and third
  44. are each the address of a 12 byte buffer, holding the parameters and results
  45. respectively:
  46.   Offset  0 (word): one of:
  47.     Sub * 256 + AL    (parameters only)
  48.     AX                (parameters and results)
  49.     AH * 256 + AL     (parameters and results)
  50.   Offset  2 (word): BX
  51.   Offset  4 (word): CX
  52.   Offset  6 (word): DX
  53.   Offset  8 (word): SI
  54.   Offset 10 (word): DI
  55. The keyword returns a value which represents the error or result flags.
  56. Each flag is held in a specific bit of the value; the remaining bits are
  57. unspecified:
  58.     Bit  0: UL flag or error flag (depending on context)
  59.     Bit  6: EQ flag
  60.     Bit  7: SL flag
  61. Thus, if the call can fail, it has failed if the returned value is odd.
  62.  
  63. When a parameter or result is described as a cstr, a qstr, a buffer, or any
  64. other construct requiring more than 2 bytes, the actual parameter or result is
  65. the address of the construct.
  66.  
  67.  
  68. The system calls are described in a standard form. The first line gives the
  69. following information:
  70. * the Fn value
  71. * the Sub value if any
  72. The second line gives the following:
  73. * The name given to the call by the SDK.
  74. * A note such as "v3.1" giving the first version of the operating system
  75.   to support the call; if omitted, all versions support it.
  76. * The word "fails" if the call can fail; if omitted, the call never fails.
  77.   - If a call can fail, then the error flag shows whether or not it did so. If
  78.     it failed, AL holds an error code between 128 and 255; this is normally
  79.     treated as a negative number between -1 and -128, found by evaluating
  80.     the expression (AX OR $FF00). AH, and any of the 5 word results that the
  81.     call would have changed, are unspecified.
  82.   - If a call cannot fail, the error flag may still be set; this should be
  83.     ignored.
  84.   - Even if a call cannot fail, bad parameters can cause a system panic.
  85. * The word "async" if the call is always asynchronous, or the word "vsync" if
  86.   it is sometimes asynchronous; if omitted, the call is synchronous.
  87.   - A synchronous call is "completed" (has carried out all its actions) when
  88.     the system call returns.
  89.   - An asynchronous call returns immediately, even though the call might not
  90.     have completed. A parameter of the call specifies a "status word", which
  91.     the call initially sets to -46 (the error code meaning "not completed).
  92.     When the relevant action has been taken or event occurs, the call
  93.     is completed, the status word is changed to indicate the result of the
  94.     call, and an IOSIGNAL is sent to the process. [This is exactly the same
  95.     behaviour as the IOA keyword.]
  96.   - If a call is "vsync", then it may be made as either a synchronous or
  97.     asynchronous call:
  98.     + to make a synchronous call, set AL to zero (the parameter giving the
  99.       address of the status word will be ignored);
  100.     + to make an asynchronous call, set AL to any other value (the address
  101.       of the status word must be valid);
  102.     + descriptions of such calls will omit AL from the list of parameters.
  103.   - An asynchronous call may complete before returning (for example if the
  104.     relevant event has already happened). In this case the process will never
  105.     see the status word with the value -46, but an IOSIGNAL is still received.
  106.   - Some asynchronous calls have a corresponding "cancel" call. This causes
  107.     the original call to be completed with the status word set to some
  108.     negative value other than -46.
  109.  
  110. This is then followed by a list of the parameters and results used by the
  111. call; any parameter not listed is ignored. For the 5 main word results, the
  112. result (if the call does not fail) is the same as the corresponding parameter
  113. (including when the former is ignored) unless a different meaning is shown
  114. following an arrow (->). For the results AH, AL, and AX, and also the result
  115. flags, the result is unspecified if no such description is given.
  116.  
  117.  
  118. For example, consider the following (non-existent) system call:
  119. Fn $12 Sub $34
  120. GetMagicCookie fails
  121.     AX: -> magic cookie table entry zero
  122.     BX: table entry number
  123.     CX: -> magic cookie entry
  124.     SI: addend -> CX out + SI in
  125. Returns entries from the magic cookie table.
  126.  
  127. This system call could be used either by:
  128.     entry0% = CALL ($3412, entry%, 0, 0, addend%)
  129. which only returns magic cookie table entry zero, or by:
  130.     LOCAL regs%(6)
  131.     regs%(1)=$3400
  132.     regs%(2)=entryno%
  133.     regs%(5)=addend%
  134.     failed%=1 AND OS ($12, ADDR(regs%()))
  135.     REM regs%(2,4,6) have not changed
  136.     IF NOT failed
  137.         entry0%=regs%(1)
  138.         entry%=regs%(3)
  139.         REM regs%(5) will equal entry%+addend%
  140.     ELSE
  141.         REM regs%(1,3,5) are undefined
  142.         error%=regs%(1) and $FF00
  143.     ENDIF
  144. which returns much more information.
  145.  
  146.  
  147. System calls
  148. ------------
  149.  
  150. Note that some system calls are deliberately not described.
  151.  
  152.  
  153. Fn $80 Sub $00
  154. SegFreeMemory
  155.     AX: -> free memory
  156. Returns the amount of free system memory, in units of 16 bytes.
  157.  
  158.  
  159. Fn $80 Sub $01
  160. SegCreate fails
  161.     AL: segment type: ordinary processes should use 1.
  162.     AX: -> segment handle
  163.     BX: (cstr) name of the segment
  164.     CX: segment size in units of 16 bytes
  165. Creates an additional memory segment. Each segment must be given a name, of the
  166. form "8.3" (i.e. up to 8 characters, optionally followed by a dot and up to 3
  167. more characters). If the name is already in use, the call will fail. Once
  168. created, the segment may be used by the process as additional memory, either
  169. via SegCopyFrom and SegCopyTo, or in assembler code (see the Psionics file
  170. KERNEL).
  171.  
  172.  
  173. Fn $80 Sub $02
  174. SegDelete fails
  175.     BX: segment handle
  176. Deletes an additional memory segment. If any other process has opened the
  177. segment, the call will fail.
  178.  
  179.  
  180. Fn $80 Sub $03
  181. SegOpen fails
  182.     AX: -> segment handle
  183.     BX: (cstr) name of the segment
  184. Opens the additional memory segment with the given name (if no such segment
  185. exists, the call will fail). The call will fail if the process has the segment
  186. open already. Except where stated, all calls using additional memory segments
  187. must be given handles from SegCreate or SegOpen calls.
  188.  
  189.  
  190. Fn $80 Sub $04
  191. SegClose fails
  192.     BX: segment handle
  193. Closes an additional memory segment which the process has open. If this was the
  194. only process with the segment open, it is deleted. Open segments are closed
  195. when a process terminates.
  196.  
  197.  
  198. Fn $80 Sub $05
  199. SegSize
  200.     AX: -> segment size
  201.     BX: segment handle
  202. Returns the size of an additional memory segment in units of 16 bytes.
  203.  
  204.  
  205. Fn $80 Sub $06
  206. SegAdjustSize fails
  207.     BX: segment handle
  208.     CX: new size