home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / demos / proart24 / Virtualise / Docs / SWIs < prev    next >
Encoding:
Text File  |  1996-08-08  |  12.2 KB  |  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 area has a handler routine then virtual memory can only
  204.         be enabled for it if this module was loaded when the area was created.
  205.  
  206.  
  207. SWI "Virtualise_End" (&4B6C2)
  208.  
  209.     Disable virtual memory in a dynamic area.
  210.  
  211.     On entry:
  212.  
  213.         R0 = The number of the dynamic area to un-virtualise.
  214.     
  215.     On exit:
  216.  
  217.         All registers preserved.
  218.  
  219.     Interrupts:
  220.  
  221.         Interrupts are enabled.
  222.         Fast interrupts are enabled.
  223.  
  224.     Processor mode:
  225.  
  226.         Processor is in SVC mode.
  227.     
  228.     Re-entrancy:
  229.  
  230.         SWI is not re-entrant.
  231.  
  232.     Use:
  233.  
  234.         Use this SWI to disable virtual memory for a dynamic area. If virtual
  235.         memory is not active for the specified dynamic area then the call
  236.         returns without error.
  237.         
  238.         If any virtual memory is associated with the area then an attempt is
  239.         made to convert it into physical memory. If it is not possible to
  240.         claim sufficient memory then the SWI will return an error, and the
  241.         virtual memory will remain active.
  242.         
  243.         If the area contains pages locked using Virtualise_Lock then an error
  244.         will be produced, and the area will remain with virtual memory active.
  245.         
  246.         If the dynamic area is removed without virtual memory being first
  247.         disabled then this SWI is implicitly called, but no check is made
  248.         for locked pages. It is better to call this SWI explicitly to allow
  249.         more elaborate checks to be performed.
  250.  
  251.  
  252. SWI "Virtualise_Lock" (&4B6C3)
  253.  
  254.     Lock pages of a dynamic area for which virtual memory has been enabled.
  255.     
  256.     On entry:
  257.     
  258.         R0 = Start of range of addresses to lock.
  259.         R1 = End of range of addresses to lock.
  260.     
  261.     On exit:
  262.     
  263.         All registers preserved.
  264.     
  265.     Interrupts:
  266.     
  267.         Interrupt status is undefined.
  268.         Fast interrupts are enabled.
  269.     
  270.     Processor mode:
  271.     
  272.         Processor is in SVC mode.
  273.         
  274.     Re-entrancy:
  275.     
  276.         SWI is not re-entrant.
  277.     
  278.     Use:
  279.     
  280.         This SWI allows an area of virtual memory to be locked in physical
  281.         memory. This enables the use of that area for interrupt routines,
  282.         and other cases which could otherwise lead to reentrancy of either
  283.         the virtual memory manager or the file system.
  284.         
  285.         All pages that are included in the range R0 to (R1-1) are locked.
  286.         This range must lie fully within the current size of a dynamic area
  287.         for which virtual memory has been enabled. A count of how many times a
  288.         page has been locked is maintained, and a page will only be unlocked
  289.         when the count reaches zero.
  290.         
  291.         Care should be taken when using this SWI to ensure that the minimum
  292.         possible number of pages are locked at any time, otherwise there may
  293.         not be sufficient physical memory available to provide the rest of
  294.         the virtual memory. It is advised that pages are locked for the
  295.         shortest possible period.
  296.         
  297.         It is possible to use this call to improve performance of the virtual
  298.         memory system by forcing particular pages to remain in memory.
  299.         However, this approach should only be used in rare circumstances
  300.         where the performance increase would be substantial. If possible,
  301.         locking pages in this manner should be a user configurable option.
  302.  
  303.  
  304. SWI "Virtualise_Unlock" (&4B6C4)
  305.     
  306.     Unlock pages of a dynamic area for which virtual memory has been enabled.
  307.     
  308.     On entry:
  309.     
  310.         R0 = Start of range of addresses to unlock.
  311.         R1 = End of range of addresses to unlock.
  312.     
  313.     On exit:
  314.     
  315.         All registers preserved.
  316.     
  317.     Interrupts:
  318.     
  319.         Interrupt status is undefined.
  320.         Fast interrupts are enabled.
  321.     
  322.     Processor mode:
  323.     
  324.         Processor is in SVC mode.
  325.         
  326.     Re-entrancy:
  327.     
  328.         SWI is not re-entrant.
  329.     
  330.     Use:
  331.     
  332.         This SWI unlocks pages that were previously locked with
  333.         Virtualise_Lock. Exactly the same values of R0 and R1 should be
  334.         used when unlocking pages as were used when they were originally
  335.         locked; unpredictable results might otherwise occur.
  336.  
  337.  
  338. SWI "Virtualise_MiscOp" (&4B6C5)
  339.  
  340.     This is for the internal use of the "!Virtualis" front-end, and should
  341.     not be used.
  342.