home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / c / callaswi / Read < prev   
Text File  |  1996-10-25  |  6KB  |  170 lines
  1. OS_CallASWI
  2. -----------
  3.  
  4. Unofficial version, written by Darren Salt
  5.  
  6. Implements the SA support SWIs from RISC OS 3.7. Suitable for RISC OS 3.1,
  7. and probably 3.5 and 3.6 as well.
  8.  
  9. DO NOT USE WITH ANY SA-AWARE VERSION OF RISC OS.
  10.  
  11. The X forms of the SWIs should be used; wherever possible, avoid using their
  12. names. It is not a good idea to assume other people have this module!
  13.  
  14. See Acorn's SA support documentation for more details of the following SWIs.
  15. (The text below is adapted from this.)
  16.  
  17.  
  18. OS_PlatformFeatures (SWI &6D)
  19. -----------------------------
  20.  
  21.     Reason code 0: read code features
  22.  
  23. On entry
  24.     R0 = 0 (reason code); all flags are reserved, so bits 16-31 must be clear
  25.  
  26. On exit
  27.     R0 = bit mask of features:
  28.          Bits     Meaning
  29.          0        Must tell OS when code areas change (by calling
  30.                   OS_SynchroniseCodeAreas)
  31.          1        Enabling, then immediately disabling interrupts will _not_
  32.                   give interrupts a chance to occur
  33.          2        Must be in 32 bit mode to read hardware vectors
  34.          3        Storing PC to memory (eg with STR or STM) stores PC+8
  35.                   rather than PC+12
  36.          4        Data aborts occur with 'full early' timing (ie. as defined
  37.                   by ARM architecture 4)
  38.  
  39.    If bit 1 of R0 set then
  40.      R1 -> routine to call (with BL) between IRQ enable & disable.
  41.  
  42. Use
  43.     This call determines features of the host processor's instruction set.
  44.     Since this implementation is not for use with StrongARM, it returns with
  45.     all bits clear.
  46.  
  47.     If you get an 'SWI not known' error, this is equivalent to R0 with bits 0
  48.     to 4 clear.
  49.  
  50.  
  51. OS_SynchroniseCodeAreas (SWI &6E)
  52. ---------------------------------
  53.  
  54.     Inform the OS that code has been altered
  55.  
  56. On entry
  57.     R0 = flags
  58.            bit 0 clear  Entire address space to be synchronised.
  59.            bit 0 set    Address range to be synchronised.
  60.            bits 1-31    Reserved
  61.  
  62.     If R0 bit 0 is set then:
  63.         R1 = low address of range (word aligned)
  64.         R2 = high address (word aligned, _inclusive_)
  65.  
  66. On exit
  67.     R0-R2 preserved
  68.  
  69. Use
  70.     This new SWI informs the OS that code has been newly generated or
  71.     modified in memory, before any attempt is made to execute the code.
  72.  
  73.     The 'full' implementation of this SWI has potentially large performance
  74.     penalties. This version, not being intended for StrongARM use, just
  75.     returns immediately.
  76.  
  77.  
  78. OS_CallASWI (SWI &6F)
  79. ---------------------
  80.  
  81.     Call a run-time determined SWI
  82.  
  83. On entry
  84.     R0-R9 as required for target SWI
  85.     R10 = target SWI number
  86.  
  87. On exit
  88.     R0-R9 as defined by target SWI
  89.     R10 preserved
  90.  
  91. Interrupt status, processor mode, re-entrancy
  92.    As defined by target SWI
  93.  
  94. Use
  95.     This new SWI allows a target SWI number to be determined at run time, and
  96.     passed in a register. This removes the need for a common idiom of dynamic
  97.     code, in language library SWI veneers for example. In an APCS-R library,
  98.     OS_CallASWIR12 may be more appropriate (see below).
  99.  
  100.     Note that OS_CallASWI is merely an alias for calling the target SWI. It
  101.     has no entry/exit conditions of its own, except for the special use of
  102.     R10. To call a target SWI with X bit set, us the X form of the SWI number
  103.     in R10; there is no distinction between OS_CallASWI and XOS_CallASWI.
  104.  
  105.     You cannot call OS_CallASWI or OS_CallASWIR12 via OS_CallASWI, since
  106.     there is no defined final target SWI in this case. (This implementation
  107.     generates an error if you attempt to do so.)
  108.  
  109.     You cannot usefully call OS_BreakPt or OS_CallAVector using OS_CallASWI,
  110.     as OS_CallASWI will corrupt the processor flags before entering the
  111.     target SWI.
  112.  
  113.     For future compatibility, you should always use this SWI in preference to
  114.     any local construction for calling a SWI by number.
  115.  
  116.     Note that this SWI calling mechanism is almost certainly faster than any
  117.     other alternative implementation, including the original _kernel_swi and
  118.     _swix code contained in older versions of the SharedCLibrary. The new
  119.     (RO3.70) SharedCLibrary now simply uses OS_CallASWIR12 for _kernel_swi
  120.     and _swix.
  121.  
  122.     OS_CallASWI cannot be called from BASIC as BASIC only passes registers
  123.     R0-R7 via its SYS instruction. It would not be useful anyway.
  124.  
  125.  
  126. OS_CallASWIR12 (SWI &71)
  127. ------------------------
  128.  
  129.     Call a run-time determined SWI
  130.  
  131. On entry
  132.     R0-R9 as required for target SWI
  133.     R12 = target SWI number
  134.  
  135. On exit
  136.     R0-R9 as defined by target SWI
  137.     R12 preserved
  138.  
  139. Interrupt status, processor mode, re-entrancy
  140.    As defined by target SWI
  141.  
  142. Use
  143.     This call is identical to OS_CallASWI, except that it uses R12 to specify
  144.     the target SWI. This may be more convenient in some environments. In
  145.     particular under APCS-R, R10 is the stack limit pointer, which must be
  146.     preserved at all times; if a SWI called using OS_CallASWI were to abort
  147.     or generate an error the run-time library would usually examine R10 and
  148.     decide that it had no stack to handle the abort or error. Therefore
  149.     APCS-R libraries must use OS_CallASWIR12 (R12 being a scratch register
  150.     under APCS-R).
  151.  
  152.  
  153.                       THE CALLASWI MODULE
  154.                       ===================
  155.  
  156. The CallASWI module provides support under RISC OS 3.1, 3.5 and 3.6 for
  157. the following SWIs:
  158.  
  159.               OS_CallASWI
  160.               OS_CallASWIR12
  161.               OS_PlatformFeatures
  162.               OS_SynchroniseCodeAreas
  163.  
  164. This will enable application programmers and library writers to use the new
  165. calls freely without any worries about backwards compatibility. There is no
  166. performance penalty for the use of these SWIs via the CallASWI module.
  167.  
  168. Unlike Acorn's implementation, this version *does* allow you to use the SWI
  169. names.
  170.