home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / virtual / VSI_C / ReadMe < prev    next >
Encoding:
Text File  |  1992-10-05  |  7.5 KB  |  194 lines
  1.  
  2.  
  3.      Virtual Store for C
  4.      -------------------
  5.  
  6.      Public Domain - David McQuillan 20th September 1992
  7.  
  8. This directory contains the first version of a Virtual Store Handler 
  9. for Acorn Ansi C.  The software in VSI_C including the virtual store 
  10. handling subroutines and the !vsilink utility is unrestricted Public 
  11. Domain.  There is no commitment to maintain the interfaces of these 
  12. routines, this software is issued with the intention of learning 
  13. from your problems and changing anything that proves unoptimal.  
  14. You are entitled (encouraged) if you can to produce your own version 
  15. of any of this software with your extension, perhaps you can produce 
  16. that definitive edition that gives what everyone wants.
  17.  
  18. With this package and a C compiler you can produce applications that 
  19. would normally occupy megabytes of space and run them in a couple of 
  20. hundred kilobytes.  Of course they will run slower if frequent paging 
  21. is necessary.
  22.  
  23. The application !vsilink is an example of VSI handling in action - 
  24. and is an essential utility.  !vsilink2 is a copy of !vsilink that is 
  25. made by running 'run_vlink'.  A '!Swap' file of 2Mbyte will be used 
  26. as a swap space in !vsilink and the files !RunImage and !RunHigh will 
  27. be created in !vsilink2.
  28.  
  29. The !vsilink utility enables an application to be built which has its 
  30. code and data in two parts, a locked down portion and a pageable 
  31. portion.  The pageable part can use the Ansi C library freely except 
  32. perhaps for signal handling and calls to system.  Calls to malloc from 
  33. the pageable part allocate pageable space and calls from the locked 
  34. down part allocate locked down space.
  35.  
  36. Treat this software with caution. It is a first version and it is 
  37. characteristic of virtual store problems that everything seems to 
  38. work fine for ages and then a weird problem crops up.  Do not run 
  39. any application generated under the Task Manager in !Edit as it can 
  40. change the page mapping at odd times.
  41.  
  42. This directory needs to be copied onto a hard disk with 3Mbyte or 
  43. more of free space before anything is run.
  44.  
  45.  
  46. !vsilink
  47. --------
  48.  
  49. !vsilink is a linker that produces !RunImage and !RunHigh in an 
  50. application directory. The two parts are linked in that direct calls 
  51. and data references can be made from one part to the other.  
  52.  
  53. Syntax is !vsilink input_files [options]*
  54. Options:
  55.    -L files Modules for low area
  56.    -P files Modules for pageable area
  57.    -O !dir  Application directory
  58.    -V file  Take file names from via file
  59.    -A file  Alias file for references from high area
  60.    -M       Produce area and symbol maps
  61.    -H       Produce this help message
  62.  
  63. Via File:
  64. Each line contains the name of a file to link or an option.
  65. A line with -P (pageable) means the following files are to be
  66. linked in the high area. A line with -L means the following
  67. files are to be put into the low area. Initially files are
  68. to be put into the low area.
  69.  
  70. Alias File
  71. Pairs of names, the first is the name referred to in the high
  72. area. The second is where the name is redirected to.
  73. For instance malloc in the high area could be redirected to
  74. VSI_malloc so that any mallocs in the high area get pageable
  75. space and mallocs in the low area get non-pageable space.
  76.  
  77. The output is put into the application directory. The low
  78. area is put in !RunImage and looks like normal Acorn object
  79. format. The High area is put in !RunHigh and must be loaded
  80. into a pageable area starting at 0x800000.
  81.  
  82. !vsilink.!Run        Just an Obey file calling !RunImage
  83. !vsilink.!RunImage   The unpaged part of !vsilink
  84. !vsilink.!RunHigh    The pageable part of !vsilink.
  85.  
  86.  
  87. The source files
  88. ----------------
  89.  
  90. WingPass Assembler source
  91. -------------------------
  92.  
  93. a.IncAsm        Include file for WingPass assembler
  94. a.vsilinkass    !RunImage header for !vsilink
  95. a.VSImanass     Assembler support for Virtual Store Handling
  96. a.VSImanRTSK    Support for C diagnostics for errors in !RunHigh.
  97.  
  98. C source
  99. --------
  100.  
  101. c.VSIclib       Intercepts for C library calls from !RunHigh
  102. c.vsilinklo     The startup code for !vsilink in !RunImage
  103. c.vsilinkhi     The main code of !vsilink in !RunHigh
  104. c.VSIman        Main support code for Virtual store Handling
  105.  
  106. Header files
  107. ------------
  108.  
  109. h.vsilink       header for !vsilink application
  110. h.VSIman        header for Virtual Store Handling use. See 
  111.                 c.vsilinklo for its use calling VSI_Setup.
  112.  
  113. Miscellaneous files
  114. -------------------
  115.  
  116. make_vlink      A call to Amu to produce !vsilink2 using
  117.                 vsilink2 and !vsilink.
  118.  
  119. run_vlink       A direct call to !vsilink producing !vsilink2.
  120.                 This also produces logfile.
  121.  
  122. logfile         A map of the application !vsilink2 produced by
  123.                 running run_vlink.
  124.  
  125. vsilink2Mk      The makefile used in make_vlink. Worth studying 
  126.                 for the line with !vsilink in it.
  127.  
  128. VSIalias        An alias file for use with !vsilink
  129.  
  130. VSIvia          A via file including the VSI routines to be 
  131.                 linked when using Virtual Store handling.
  132.  
  133. ReadMe          This read-me file
  134.  
  135.  
  136. The linked form
  137. ---------------
  138.  
  139. The modules 'o.VSIclib o.VSIman o.VSImanass o.VSImanRTSK' must be
  140. linked to the low store part of an application along with the stubs 
  141. module <c$LibRoot>o.stubs using !vsilink.
  142.  
  143. The initial entry must be into !RunImage and call VSI_Setup as in 
  144. c.vsilinklo.  This specifies the minimum size to page into, the 
  145. virtual store size, and the application directory name.
  146.  
  147. A virtual store space will be set up in the directory and !RunHigh 
  148. loaded.  Calls can then be made to the high area as desired.
  149.  
  150. Data in the high area should never be passed over directly to the 
  151. system.  Calls to the C routines including fread and fwrite are ok, 
  152. dangerous ones are intercepted using VSIalias. It is ok to pass over 
  153. references to local space on the stack. Calls to system or using 
  154. signal should be avoided - I'm not sure of all the consequences.
  155.  
  156. The modules in !RunImage should call the intercept routines VSI_<name> 
  157. if there is any chance that a parameter may be from !RunHigh, or else 
  158. should copy the parameter to a low area - for example the stack.  The 
  159. intercept routines in VSIclib and File_Size in vsilinklo show the 
  160. general pattern of what has to be done.
  161.  
  162. And there you have it. The application can be used single tasking 
  163. but not under the task manager in !Edit as it mangles up the addressing 
  164. at odd times. To produce an application running under the Wimp the 
  165. system calls should be placed in !RunImage.  VSI_Save should be called 
  166. before Wimp_Poll and VSI_Restore called afterwards so the space is 
  167. restored as it was before the Poll.
  168.  
  169.  
  170. Where I'd like it to go- ideas for development
  171. ----------------------------------------------
  172.  
  173. I would like to centralize the virtual store allocation into a single 
  174. application !VSI which would allocate space from a central pool.  This 
  175. would have an associated module which would be better at trapping when 
  176. the page map changes.  Doing this would allow all the pageable space of 
  177. an application to be paged out and used by another application - 
  178. useful for allowing a number of large Wimp applications to be  
  179. permanently loaded and paged out while waiting for the user to do 
  180. something with them.
  181.  
  182. I would like to get it to work with the task manager or have some 
  183. equivalent facility built in.
  184.  
  185. I would like to be able to load a page for a virtual store interrupt 
  186. in the background whilst executing another task - this would have to 
  187. be only if the application was willing to relinquish control.
  188.  
  189. Support for debugging via !DDT should be put in (probably requires 
  190. Acorn to do something).
  191.  
  192. I would like it to be eventually supported by Acorn or someone else 
  193. who could look after it properly.
  194.