home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / languages / progs / gcc / Virtual / !Virtual / !Help < prev    next >
Encoding:
Text File  |  1995-02-28  |  16.7 KB  |  355 lines
  1. !Virtual 0.37
  2. =============
  3.  
  4. !Virtual supplies virtual memory under RISC OS 2/3, allowing a task to
  5. believe it has upto 24M of memory, yet have a draggable WimpSlot that can be
  6. set as desired. However, it is fairly restrictive in what can be done -
  7. basically only line based (non desktop) programs can be used. This is quite
  8. sufficient to run C compilers, though, which is what we wanted it for. It is
  9. fully compatible with the Acorn DDE development environment.
  10.  
  11. It has been tested on a wide range of machines (ARM2/3, RISC OS 2/3, MEMC
  12. 1/1a, 1/2/4/8MB RAM) so should run on pretty much anything. It will only
  13. work on  machines with 8, 16 or 32Kb page sizes currently (which covers all
  14. older Acorn RISC computers).
  15.  
  16. ****************************************************************************
  17. NOTE: that the 'Risc PC' and newer machines use a completely different
  18. memory controller which means that !Virtual will not work. Because of the way
  19. that the Risc PC manages memory, it makes more sense for a 'true' demand-
  20. paged virtual memory manager to be written, rather than hacking !Virtual
  21. about to get it to work. I may do this one day if I can find the time.
  22. ****************************************************************************
  23.  
  24. All RISC OS swi calls run in supervisor mode. On the ARM2/ARM3 a prefetch or
  25. data abort corrupts svc_R14, and RISC OS isn't written to support this. So
  26. it is pretty much of a dead loss to let any swis access virtual memory.
  27. Also, the Wimp is very grungy with its memory mapping, and basically dies if
  28. it sees even the slightest change to the memory map.
  29.  
  30. So !Virtual acts as a replacement for taskwindow, and uses the same
  31. interface to !(Src)Edit for i/o. The task under !Virtual runs with a
  32. virtualised memory map, strictly in user mode. It is preempted from time to
  33. time, to allow the Wimp to continue, but everytime this is done the memory
  34. map has to be put back exactly as the Wimp expects to find it. (Can you say
  35. inefficient?) Any swis that the task tries to issue are intercepted and
  36. "vetted" by !Virtual. Many are treated specially in that certain areas of
  37. memory are forced to be paged in, or large file loads are broken up into
  38. chunks and done page by page with the memory arranged as the Wimp thinks it
  39. should be, in case the filing system expands the RMA. Only swis that
  40. !Virtual understands can be sure of being treated correctly, so any unknown
  41. ones return an error to the application - this means that the task is cut
  42. off from the greater part of RISC OS, and should really be thought of as
  43. running under a different operating system, that just happens to be hosted
  44. on RISC OS.
  45.  
  46. At the moment, only a relatively small number of SWIs have been implemented
  47. (see file 'Bits.SWIs_list') - please contact us if you want a particular SWI
  48. to be supported.
  49.  
  50. How to use:
  51. ==========
  52.  
  53. The module supplies one * command, "*virtual" that is designed as a
  54. replacement for *taskwindow, and accepts a similar set of parameters. Try
  55. "virtual basic -ctrl -discslot 24M" from an obey file, for instance. This
  56. will run basic, which will believe it has 24M at its disposal. (Though if
  57. you don't have that much disk space you had better not use it.) Really, it
  58. only has a WimpSlot the size given by the "Next" Slot, and this can be
  59. dragged up or down in the taskmanager. Notice that the command to be
  60. executed is one parameter, so will have to be quoted if its more than one
  61. word.
  62.  
  63. NOTE! You need a task window 'provider' application loaded to use Virtual.
  64. For instance, !Edit or !SrcEdit. Some other programs provide task window
  65. facilities. eg, Brian's !VMode which gives the user a graphical task window.
  66.  
  67. A new feature for !Virtual is Acorn DDE compatibility - you can setup a
  68. command alias for the 'TaskWindow' command, and all references to
  69. taskwindows will go through !Virtual instead. Hence Ctrl-F12 (on the
  70. TaskManager menu) will start a virtual taskwindow, and !AMU, !CC, !Find,
  71. etc. will all use virtual taskwindows instead of 'real' ones - completely
  72. transparently. All that is required to use this facility is to set ;
  73.  
  74.   *Set Alias$TaskWindow "Virtual %*0"
  75.  
  76. This can be done in the '!Virtual.!Run' file, or in a system !Boot file, or
  77. whatever. To access a 'real' taskwindow, you can either use '*%TaskWindow',
  78. or do a '*UnSet Alias$TaskWindow'.
  79.  
  80. Virtual runs code in one of three states. "Virtual" mode is when the memory
  81. map is changed, special abort handlers are installed, and all user mode swis
  82. with a flat svc stack are redirected. (The flat restriction is because
  83. nfs/econet sometimes drop back into user mode to do work.) "Ext" mode is
  84. used to execute some swis - the memory map is still changed, but no abort
  85. handlers are in place, as they shouldn't happen. Any that do will be caught
  86. by an error handler. OS_WriteC is trapped, so that any output produced can
  87. be redirected to the taskwindow. "Normal" mode is when the memory map is put
  88. back as the Wimp expects, so we can call Wimp_Poll and other things that may
  89. want to rearrange it. OS_WriteC is still trapped, except for the very moment
  90. of Wimp_Poll, and after being in normal mode, I always rescan the memory map
  91. to see if anything has changed.
  92.  
  93. All filing system operations, and most OS_CLIs run in normal mode. If a new
  94. application is started as a result of a command, it is trapped by an upcall
  95. handler, which enters virtual mode with the virtual memory map exactly
  96. matching the application one, and installs lots of vectors. This means that
  97. the WimpSlot must be large enough to *load* the (squeezed) executable of
  98. something that is run.
  99.  
  100. Future: OS_CLIS that start with the character "/", will be specially
  101. treated, to allow the running of executable files that are bigger than the
  102. real WimpSlot that virtual posesses.
  103.  
  104. The *Virtual command allows a task to be run with virtual memory.
  105. Syntax: *Virtual [<command>] [-wimpslot <n>K] [-discslot <n>M]
  106.           [-name <taskname>] [-nice <n>] [-pagefile <filename>]
  107.           [-task <x>] [-txt <x>] [-ctrl] [-display] [-quit]
  108.  
  109.   <command> is the command to be executed
  110.   -wimpslot sets the physical memory to be allocated
  111.   -discslot sets the virtual memory, default 24M
  112.   -name sets the task name
  113.   -nice sets the task priority: 9 low priority, 0 high priority, default 4
  114.   -pagefile sets the swap file for this virtual task - defaults to the
  115.    !SwapDir application
  116.   -task supplies the address of the parent task handle [NOT USER]
  117.   -txt supplies the address of the txt identifier      [NOT USER]
  118.   -ctrl allows control characters through
  119.   -display opens the task window immediately, rather than waiting for a
  120.    character to be printed
  121.   -quit makes the task quit after the command even if the task window has
  122.    been opened
  123.  
  124. Note that fields must be in " " if they comprise more than one word
  125.  
  126. Things to note about the source code:
  127. ====================================
  128.  
  129. Virtual is mostly written in C, with a minimal amount of assembler. It uses
  130. no linked libraries at all. It runs mostly in supervisor mode, but there is
  131. some nefarious switching needed for Wimp_Poll to work.
  132.  
  133. To avoid messing with the supervisor stack, I use R12 as stack pointer in
  134. the C code, and R13 can remain untouched as there's no stack limit. This is
  135. effectively the obsolete APCS_A register allocation. The C compiler is made
  136. to generate assembler source, and the register definitions are then changed
  137. by a sed script.
  138.  
  139. printf is a module written solely to provide a print_f swi so that I can
  140. avoid messing with the C library in the main module, yet produce debug
  141. output easily.
  142.  
  143. Programs running under !Virtual should not be thought of as running under
  144. RISC OS. They have access to a very limited subset of particular SWIs that
  145. I've implemented properly. Further SWI routines accepted with enthusiasm. 
  146.  
  147. Contributors:
  148. ============
  149.  
  150. Many thanks to Ferdinand Oeinck (ferdinan@oeinck.waterland.wlink.nl) for his
  151. continuing work to !Virtual.
  152.  
  153. Reporting problems:
  154. ==================
  155.  
  156. Please read this BEFORE sending me any reports of problems! With a complex
  157. (and buggy!) program like !Virtual, I get a fair few email messages of the
  158. form "I ran your !Virtual, and it didn't work - what am I doing wrong?"
  159.  
  160. PLEASE don't send me such unhelpful comments! Really, I need to know as much
  161. of the following as you can provide in the initial email;
  162.  
  163. * Your machine - model, memory, harddisc (interface), version of RISC OS,
  164.   other hardware or software that may be interfering with !Virtual.
  165. * The application you are running to provide task windows (eg, !edit or
  166.   !srcedit) and which version
  167. * Version number of !Virtual
  168. * Exactly what you did from machine switch on until virtual failed to work
  169.   as expected
  170. * Exactly what happened - eg, did the machine crash completely with the
  171.   mouse pointer stopping ?
  172. * And ideally, the source file and changes required to fix the problem ;-) 
  173.   Obviously if you are not an experienced programmer you can't do this.
  174.  
  175. Distribution:
  176. ============
  177.  
  178. This software may be freely redistributed, so long as only a reasonable
  179. copying or media charge is made, and all files I distribute are included. I
  180. retain copyright to the code. Commercial (including magazine) distribution,
  181. or distributing modified versions of this please contact me - I am normally
  182. happy for it to be reused in other free software, but like to avoid deviant
  183. versions of mine causing trouble.
  184.  
  185. I am not asking for money, but if you like and use it I would be surprised
  186. and amazed by any contributions, and you will receive a disc with latest
  187. versions on. (>£10, say)
  188.  
  189. Brian Brunswick                              brian@aleph1.co.uk (Internet)
  190. Fairview                                  OR Brian.Brunswick@cl.cam.ac.uk          
  191. Avenue des Hirondelles
  192. Pool-in-WharfeDale
  193. Leeds
  194. LS21 1EY
  195. UK
  196. 0532 843737
  197.  
  198. Versions later than 0.20:
  199. ========================
  200.  
  201. Because Brian is now out 'in the real world' I (Nick Smith) am acting as a
  202. first line of support for !Virtual. I have tidied it up for the first public
  203. release, and will improve the program as I get feed back from users, etc.
  204. Currently, Brian wrote 90% of the actual software - so send him all that
  205. money in gratitude !
  206.  
  207. Please email or snail-mail me comments, bug reports, requests for new
  208. features, etc. and I will hopefully have the time to deal with them. If you
  209. make any modifications to the code, please send them to me rather than
  210. giving out copies - I would like to coordinate new releases. Thanks.
  211.  
  212. I can be contacted at the following address ;
  213.  
  214. N.A. Smith                                    nas@ant.co.uk (Internet)
  215. ANT Limited
  216. PO Box 300                      Try checking out;
  217. Cambridge                      http://www.ant.co.uk/
  218. CB1 2EG                 
  219.  
  220. Revision history:
  221. ================
  222.  
  223. Modifications to v0.21 (13-Mar-93) [ß-release]
  224.   - !SwapDir resources application
  225.   - Improved documention; added installation instructions, updated info,
  226.     added revision history, etc
  227.   - removed compilation dependency on having brian's harddrive 8-)
  228.   - did some slightly better (but still awful) !Sprites, with !Sprites22
  229.   - detailed *Help command provided
  230.   - cleaned up code & file structure generally
  231.   - cleaned up test/example software
  232.  
  233. Modifications to v0.22 (14-Mar-93) [release]
  234.   - Made small number of changes that Brian asked for
  235.  
  236. Modifications to v0.23 (12-Apr-93) [release]
  237.   - Bug reports showed that using pseudo-filing system Swap: was not
  238.     RISC OS 2 compatible (really - people still use it!), so some 
  239.     very minor changes to use <Swap$Path>PageFile0 instead of
  240.     Swap:PageFile0
  241.  
  242. Modifications to v0.24 (20-Apr-93)
  243.   - Some more ideas for the 'ToDo' file
  244.   - New SWI provided; Virtual_TaskInfo, like TaskWindow_TaskInfo
  245.   - Some more SWIs supported including OS_Mouse, OS_SWINumberFromString,
  246.     OS_ReadMonotonicTime and TaskWindow_TaskInfo
  247.   - 'Bits.SWIs_list' file created - list of all supported SWIs
  248.   - Better sprites for !SwapDir
  249.   - Started work on !StartTask; a simple FrontEnd application that 
  250.     gives a 'friendly' user interface to the *Virtual command
  251.  
  252. Modifications to v0.25 (29-Jun-93) 
  253.   - Some useful bugfixes/contributed code from Ferdinand Oeinck ;
  254.   - bugfix in MEMC page initialisation, now in FixMemMaps(), so that
  255.     programs called from system() now return correctly. This was the serious
  256.     problem that was stopping the Arc gcc compiler port from working!
  257.   - Wimp_SlotSize SWI is now interpreted better
  258.   - OS_Control, OS_ReadVduVariables, OS_SetVarVal, and OS_ConvertHex8 SWIs
  259.     added
  260.   - It is now possible to start Virtual in the Supervisor mode with the
  261.     command ie 'Virtual "gos" -ctrl -wimpslot 3M'. When a program called
  262.     from the prompt finishes, Virtual will stop, but you can get the prompt
  263.     back by choosing 'Reconnect' from the Taskwindow menu.
  264.   - Escape handling is now implemented, and works *most* of the time.
  265.   - NOTE! This is an 'emergency' release to fix the gcc problems - lots more
  266.     work will be done before the next release, hopefully mid-August.
  267.     Some of the code new to 0.24 hasn't been finished/tested.
  268.  
  269. Modifications to v0.26 (02-Jul-93)
  270.   - Another bugfix release - some more fixes from Ferdinand
  271.  
  272. Modifications to v0.27 (06-Jul-93) [release]
  273.   - Some minor bugfixes, and a new gcc example makefile test for !Virtual
  274.   - MAJOR bugfix for 16Kb pagesize (ie, 2MB RAM machines) *AT LAST* :-)
  275.   - This version sent to Newcastle info-server
  276.  
  277. Modifications to v0.28 (09-Jul-93) 
  278.   - Problem with RISC OS 2 command parameters fixed
  279.   - Now taskwindow compatible. Use *set alias$taskwindow "virtual %*0"
  280.   - Mistake in hires sprites being defined in custom Mode 61 fixed
  281.   - !VDump won't run under RISC OS 2, so now correctly checks the OS when
  282.     loading, and exits cleanly under RISC OS 2.
  283.  
  284. Modifications to v0.29 (21-Jul-93)
  285.   - Sent SWI chunk allocation request to Acorn Customer Support
  286.   - Improved documentation on -pagefile, -txt, -task, -nice and -discslot
  287.     parameters
  288.   - Implemented Virtual_TaskInfo SWI
  289.   - Implemented -discslot, and altered -wimpslot to physical RAM setting
  290.   - Implemented -nice parameter for sceduling, controlling both timeslice,
  291.     and delay to next wimp_pollidle
  292.   - Fixed a problem with command parameters on subsequent OS_GetEnv (may
  293.     have reintroduced RO2 problem :-(
  294.                     
  295. Modifications to v0.30 (22-Jul-93)
  296.   - Implemented DDEUtils_Prefix SWI handler (still broken :-(
  297.   - Added appropriate code to deal with extended command lines from DDE
  298.     FrontEnd tools
  299.   - Added OS_Plot SWI
  300.  
  301. Modifications to v0.31 (23-Jul-93)
  302.   - Finally sorted out !StartTask frontend application by using a 16 byte
  303.     utility to call wimp_starttask on extended command line
  304.  
  305. Modifications to v0.32 (10-Aug-93)
  306.   - Finally fixed problem with DDEUtils_Prefix - thanks Ferdinand!
  307.     now fully compatible with Acorn DDE suite, just enable the *Taskwindow
  308.     alias command in the !Run file and the DDE will use virtual taskwindows
  309.   - Added details of taskwindow alias to !Help file
  310.   - Noticed problem running !StartTask with Alias$TaskWindow set (a virtual
  311.     task cannot be run from inside another virtual task currently) so we
  312.     just ignore any !StartTask commands in this case
  313.  
  314. Modifications to v0.33 (16-Aug-93) [release]
  315.   - New patch for an interesting SWI call ;-) Fixed mistake in xswis.h
  316.   - Continuing problems with command parameters under RISCOS 2. It is
  317.     unlikely that we can fix these in the near future - try getting RO3!
  318.   - Stopped !StartTask from loading under RO2 - again, this won't be
  319.     fixed
  320.   - Saved a bit of memory by compiling virtual with -ff (no embedded
  321.     function names)
  322.  
  323. Modifications to v0.34 (19-Aug-93) 
  324.   - Support added for OS_Byte, 129 call - required for some development s/w
  325.   - Noticed that -quit/display/ctrl flags seem to be ignored completely!
  326.     fixed up -quit so that it at least works(ish)
  327.   - ShellCLI_TaskQuit didn't work (ignored) so built an alias for it so
  328.     it works in both normal and virtual taskwindows
  329.   - Support for Wimp_SendMessage SWI call
  330.  
  331. Modifications to v0.35 (24-Aug-93) 
  332.   - Got Acorn-allocated SWI chunk number :-)
  333.   - Put together some ideas for the planned !Vmonitor application - but
  334.     I'm not writing it!
  335.                       
  336. Modifications to v0.36 (06-Sep-93) 
  337.   - Expanded on ideas for planned !VMonitor application
  338.   - Deleted redundant poll.s and pager.s files from distribution
  339.   - Added OS_File,0 and OS_File,10 SWI handlers, since some versions of
  340.     squeeze (?) seem to require this
  341.   - Added (c) messages to all source files
  342.   - Removed 'Bits' module from inside !Virtual application
  343.   - Pulled out all the #ifdef's for FIXED_SYSTEM_VERSION, TASKWINDOW_,
  344.     etc - the new code works, so I've removed the old code completely
  345.   - bracketed some more debugging messages with *ifdef DEBUG's
  346.  
  347. Modifications to v0.37 (07-Sep-93) [release]
  348.   - Fixed the 'task input' code - not perfect, but works for all normal
  349.     inputs, and doesn't crash
  350.   - Tested on RISCOS 2 machine - text files reformatted for a Mode 12
  351.     screen
  352.   - ReBuilt 'Start' code for !StartTask - now uses new Virtual SWI chunk
  353.   - Made a binaries-only distribution for a wider audience
  354.                          
  355.