home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / demos / proart24 / Virtualise / Docs / SWIs < prev    next >
Text File  |  1996-08-08  |  12KB  |  342 lines
  1. File        : SWIs
  2. Date        : 08-Aug-96
  3. Author      : © A.Thoukydides, 1995, 1996
  4. Description : Description of the SWIs provided by the "Virtualise" module.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. The Virtualise module can be controlled directly via a number of SWIs
  10. (SoftWare Interrupts). These are described in detail below. However, they are
  11. really only required by programs which offer control over how virtual memory
  12. is used; just using the module to provide virtual memory for other author's
  13. software does not require use or knowldedge of these SWIs.
  14.  
  15. The interface is logically split into two parts: existing RISC OS calls whose
  16. behaviour has been modified, and new SWIs provided by the module.
  17.  
  18.  
  19. CHANGES TO OPERATING SYSTEM SWIS
  20.  
  21. SWI "OS_DynamicArea" (&66)
  22.  
  23.     This SWI has been extended to allow dynamic areas larger than physical
  24.     RAM to be created, and to return the logical size of the area rather than
  25.     the physical size.
  26.     
  27.     An extra area flag has been defined:
  28.     
  29.         Bit Meaning
  30.         31  Virtual memory is active for dynamic area. If this bit is set
  31.             when the area is created then virtual memory is activated
  32.             immediately. Note that no error is produced if it is not possible
  33.             to start virtual memory for the new dynamic area.
  34.  
  35.     Note that reading this flag bit only gives meaningful results if the
  36.     Virtualise module is loaded at the time. This is because the OS is
  37.     perfectly happy to maintain and return this bit itself.
  38.  
  39.     The area size may be specified to be larger than the amount of RAM in the
  40.     computer, up to a limit of 256MB. However, if -1 is specified for the
  41.     maximum size of the area then the maximum size is set to the limit set
  42.     using Virtualise_Configure (by default the amount of physical RAM (as at
  43.     present). The maximum may be specified larger than the RAM size even if
  44.     virtual memory is not being started initially. If Virtualise_Start is
  45.     later used then the virtual memory will be able to utilise all the of the
  46.     allocated address space.
  47.     
  48.     One important point to note is that there is only 3.5GB of address space
  49.     available in the machine. This can soon get used up if all applications
  50.     ask for the maximum possible of 256MB. This problem is made worse by a
  51.     bug in Filecore which fails with top bit set addresses (over 2GB). Other
  52.     applications, such as !ChangeFSI, sometimes fall over at even lower
  53.     addresses.
  54.  
  55.  
  56. SWI "OS_ChangeDynamicArea" (&2A)
  57.  
  58.     If used on an area that has virtual memory active this SWI adjusts the
  59.     logical size of the area, otherwise the physical size is adjusted. In
  60.     practice this means that this call can be used by the application without
  61.     worrying whether virtual memory is active.
  62.  
  63.  
  64. SWI "OS_ReadDynamicArea" (&5C)
  65.  
  66.     If used on an area that has virtual memory active this SWI reads the
  67.     logical size of the area, otherwise the behaviour is the same as before.
  68.     In practice this means that this call can be used by the application
  69.     without worrying whether virtual memory is active.
  70.  
  71.  
  72. SWIS PROVIDED BY VIRTUALISE
  73.  
  74. The SWI chunk starting at &4B6C0 has been officially allocated by Acorn for
  75. use by this module.
  76.  
  77. SWI "Virtualise_Configure" (&4B6C0)
  78.  
  79.     Configure logical and physical memory usage.
  80.  
  81.     On entry:
  82.     
  83.         R0 = Set the amount of logical address space, in bytes, allocated for
  84.              dynamic areas when -1 is passed to OS_DynamicArea 0, or -1 to
  85.              read current value.
  86.         R1 = Amount of memory to claim automatically, in bytes, or -1 to read
  87.              current value.
  88.         R2 = Amount of memory to leave free, in bytes, or -1 to read current
  89.              value.
  90.  
  91.     On exit:
  92.     
  93.         R0 = The size of address space to allocate.
  94.         R1 = The amount of memory to claim, in bytes.
  95.         R2 = The amount of memory to leave free, in bytes.
  96.  
  97.     Interrupts:
  98.  
  99.         Interrupt status is undefined.
  100.         Fast interrupts are enabled.
  101.  
  102.     Processor mode:
  103.  
  104.         Processor is in SVC mode.
  105.     
  106.     Re-entrancy:
  107.  
  108.         SWI is not re-entrant.
  109.  
  110.     Use:
  111.     
  112.         This call provides control over how much real memory to claim, and
  113.         how much to leave free. These values are only treated as guidelines.
  114.         In particular the user may drag the bar in the Task Manager or the
  115.         specified values may lie outside the range of required or useful
  116.         memory.
  117.         
  118.         Do not rely on any particular default values. They may be altered by
  119.         another application, the configuration specified by the user, or they
  120.         could change in a future release of this module.
  121.         
  122.         The recommended way of using this call (if it is used at all) is to
  123.         include an option in the application configuration window for minimum
  124.         amount of memory to claim and minimum memory to leave free. When the
  125.         window is opened this call should be used to read the current
  126.         settings. When the user selects OK or Save this call should be used
  127.         to set the values. If the application saves a configuration then it
  128.         should call this SWI when it starts to set the required values. The
  129.         application should not normally set these values any more frequently
  130.         - it is likely to result in confusing behaviour for the user if more
  131.         that one application is using the virtual memory system.
  132.         
  133.         It is also possible to control how much address space is allocated
  134.         for dynamic area which are created with -1 passed for the maximum
  135.         size. This allows badly written programs to be used on machines with
  136.         a large memory without using ridiculously large sections of the
  137.         logical address space. This option should not normally be used by
  138.         applications themselves - it is intended for use by the user to
  139.         control wastage of logical address space by programs which are not
  140.         aware of virtual memory.
  141.  
  142.  
  143. SWI "Virtualise_Start" (&4B6C1)
  144.  
  145.     Start virtual memory in an existing dynamic area.
  146.  
  147.     On entry:
  148.  
  149.         R0 = The number of the dynamic area to virtualise.
  150.         R1 = Maximum size of area (reserved logical address space), or -1 to
  151.              use maximum size of the dynamic area.
  152.         R2 = Pointer to name to use for swap file. If this is a null pointer
  153.              then a name is chosen automatically.
  154.  
  155.     On exit:
  156.  
  157.         All registers preserved.
  158.  
  159.     Interrupts:
  160.  
  161.         Interrupts are enabled.
  162.         Fast interrupts are enabled.
  163.  
  164.     Processor mode:
  165.  
  166.         Processor is in SVC mode.
  167.     
  168.     Re-entrancy:
  169.  
  170.         SWI is not re-entrant.
  171.  
  172.     Use:
  173.     
  174.         After a dynamic area has been created using OS_DynamicArea 0 (as usual)
  175.         use this SWI to enable virtual memory.
  176.         
  177.         The initial size of the virtual memory is the same as the actual size
  178.         of the dynamic area; any data already in the area is copied into the
  179.         virtual memory. If there is no data in the area when virtual memory is
  180.         enabled then it would be more efficient to shrink the area to 0 size
  181.         before using this SWI, and to grow the virtual memory with
  182.         OS_ChangeDynamicArea afterwards.
  183.         
  184.         Normally virtual memory is restricted to being within the logical
  185.         address space of the dynamic area. However, if more contiguous
  186.         logical address space has been reserved it is possible to set R1 to
  187.         this value to allow its use. It should never be necessary to use this
  188.         option since the Virtualise module if capable of creating dynamic
  189.         areas with maximum sizes greater than the RAM size of the computer.
  190.  
  191.         The swap file will normally be placed in the automatically created
  192.         directory <Virtualise$SwapDir>. This may be changed by specifying
  193.         a full pathname in R2. The variable <Virtualise$SwapDir> defaults to
  194.         <Wimp$ScrapDir>.Virtualise.
  195.         
  196.         Note that the following flags must be set:
  197.         
  198.             bit 4   0 - Area is bufferable
  199.             bit 5   0 - Area is cacheable
  200.             bit 6   0 - Area is singly mapped.
  201.             bit 8   0 - Area does not require specific physical pages
  202.  
  203.         If the dynamic