RISC DISC 1/RISC_DISC_1.iso/pd_share/code/virtual/!Virtual/!Help

Text File | 1993-09-10 | 16.1 KB | 346 lines

!Virtual 0.37
=============

!Virtual supplies virtual memory under RISC OS 2/3, allowing a task to
believe it has upto 24M of memory, yet have a draggable WimpSlot that can be
set as desired. However, it is fairly restrictive in what can be done -
basically only line based (non desktop) programs can be used. This is quite
sufficient to run C compilers, though, which is what we wanted it for. It is
fully compatible with the Acorn DDE development environment.

It has been tested on a wide range of machines (ARM2/3, RISC OS 2/3, MEMC
1/1a, 1/2/4/8MB RAM) so should run on pretty much anything. It will only
work on  machines with 8, 16 or 32Kb page sizes currently (which covers all
Acorn RISC computers at the moment).

All RISC OS swi calls run in supervisor mode. On the ARM2/ARM3 a prefetch or
data abort corrupts svc_R14, and RISC OS isn't written to support this. So
it is pretty much of a dead loss to let any swis access virtual memory.
Also, the Wimp is very grungy with its memory mapping, and basically dies if
it sees even the slightest change to the memory map.

So !Virtual acts as a replacement for taskwindow, and uses the same
interface to !(Src)Edit for i/o. The task under !Virtual runs with a
virtualised memory map, strictly in user mode. It is preempted from time to
time, to allow the Wimp to continue, but everytime this is done the memory
map has to be put back exactly as the Wimp expects to find it. (Can you say
inefficient?) Any swis that the task tries to issue are intercepted and
"vetted" by !Virtual. Many are treated specially in that certain areas of
memory are forced to be paged in, or large file loads are broken up into
chunks and done page by page with the memory arranged as the Wimp thinks it
should be, in case the filing system expands the RMA. Only swis that
!Virtual understands can be sure of being treated correctly, so any unknown
ones return an error to the application - this means that the task is cut
off from the greater part of RISC OS, and should really be thought of as
running under a different operating system, that just happens to be hosted
on RISC OS.

At the moment, only a relatively small number of SWIs have been implemented
(see file 'Bits.SWIs_list') - please contact us if you want a particular SWI
to be supported.

How to use:
==========

The module supplies one * command, "*virtual" that is designed as a
replacement for *taskwindow, and accepts a similar set of parameters. Try
"virtual basic -ctrl -discslot 24M" from an obey file, for instance. This
will run basic, which will believe it has 24M at its disposal. (Though if
you don't have that much disk space you had better not use it.) Really, it
only has a WimpSlot the size given by the "Next" Slot, and this can be
dragged up or down in the taskmanager. Notice that the command to be
executed is one parameter, so will have to be quoted if its more than one
word.

NOTE! You need a task window 'provider' application loaded to use Virtual.
For instance, !Edit or !SrcEdit. Some other programs provide task window
facilities. eg, Brian's !VMode which gives the user a graphical task window.

A new feature for !Virtual is Acorn DDE compatibility - you can setup a
command alias for the 'TaskWindow' command, and all references to
taskwindows will go through !Virtual instead. Hence Ctrl-F12 (on the
TaskManager menu) will start a virtual taskwindow, and !AMU, !CC, !Find,
etc. will all use virtual taskwindows instead of 'real' ones - completely
transparently. All that is required to use this facility is to set ;

  *Set Alias$TaskWindow "Virtual %*0"

This can be done in the '!Virtual.!Run' file, or in a system !Boot file, or
whatever. To access a 'real' taskwindow, you can either use '*%TaskWindow',
or do a '*UnSet Alias$TaskWindow'.

Virtual runs code in one of three states. "Virtual" mode is when the memory
map is changed, special abort handlers are installed, and all user mode swis
with a flat svc stack are redirected. (The flat restriction is because
nfs/econet sometimes drop back into user mode to do work.) "Ext" mode is
used to execute some swis - the memory map is still changed, but no abort
handlers are in place, as they shouldn't happen. Any that do will be caught
by an error handler. OS_WriteC is trapped, so that any output produced can
be redirected to the taskwindow. "Normal" mode is when the memory map is put
back as the Wimp expects, so we can call Wimp_Poll and other things that may
want to rearrange it. OS_WriteC is still trapped, except for the very moment
of Wimp_Poll, and after being in normal mode, I always rescan the memory map
to see if anything has changed.

All filing system operations, and most OS_CLIs run in normal mode. If a new
application is started as a result of a command, it is trapped by an upcall
handler, which enters virtual mode with the virtual memory map exactly
matching the application one, and installs lots of vectors. This means that
the WimpSlot must be large enough to *load* the (squeezed) executable of
something that is run.

Future: OS_CLIS that start with the character "/", will be specially
treated, to allow the running of executable files that are bigger than the
real WimpSlot that virtual posesses.

The *Virtual command allows a task to be run with virtual memory.
Syntax: *Virtual [<command>] [-wimpslot <n>K] [-discslot <n>M]
          [-name <taskname>] [-nice <n>] [-pagefile <filename>]
          [-task <x>] [-txt <x>] [-ctrl] [-display] [-quit]

  <command> is the command to be executed
  -wimpslot sets the physical memory to be allocated
  -discslot sets the virtual memory, default 24M
  -name sets the task name
  -nice sets the task priority: 9 low priority, 0 high priority, default 4
  -pagefile sets the swap file for this virtual task - defaults to the
   !SwapDir application
  -task supplies the address of the parent task handle [NOT USER]
  -txt supplies the address of the txt identifier      [NOT USER]
  -ctrl allows control characters through
  -display opens the task window immediately, rather than waiting for a
   character to be printed
  -quit makes the task quit after the command even if the task window has
   been opened

Note that fields must be in " " if they comprise more than one word

Things to note about the source code:
====================================

Virtual is mostly written in C, with a minimal amount of assembler. It uses
no linked libraries at all. It runs mostly in supervisor mode, but there is
some nefarious switching needed for Wimp_Poll to work.

To avoid messing with the supervisor stack, I use R12 as stack pointer in
the C code, and R13 can remain untouched as there's no stack limit. This is
effectively the obsolete APCS_A register allocation. The C compiler is made
to generate assembler source, and the register definitions are then changed
by a sed script.

printf is a module written solely to provide a print_f swi so that I can
avoid messing with the C library in the main module, yet produce debug
output easily.

Programs running under !Virtual should not be thought of as running under
RISC OS. They have access to a very limited subset of particular SWIs that
I've implemented properly. Further SWI routines accepted with enthusiasm.

Contributors:
============

Many thanks to Ferdinand Oeinck ([e-mail]) for his
continuing work to !Virtual.

Reporting problems:
==================

Please read this BEFORE sending me any reports of problems! With a complex
(and buggy!) program like !Virtual, I get a fair few email messages of the
form "I ran your !Virtual, and it didn't work - what am I doing wrong?"

PLEASE don't send me such unhelpful comments! Really, I need to know as much
of the following as you can provide in the initial email;

* Your machine - model, memory, harddisc (interface), version of RISC OS,
  other hardware or software that may be interfering with !Virtual.
* The application you are running to provide task windows (eg, !edit or
  !srcedit) and which version
* Version number of !Virtual
* Exactly what you did from machine switch on until virtual failed to work
  as expected
* Exactly what happened - eg, did the machine crash completely with the
  mouse pointer stopping ?
* And ideally, the source file and changes required to fix the problem ;-)
  Obviously if you are not an experienced programmer you can't do this.

Distribution:
============

This software may be freely redistributed, so long as only a reasonable
copying or media charge is made, and all files I distribute are included. I
retain copyright to the code. Commercial (including magazine) distribution,
or distributing modified versions of this please contact me - I am normally
happy for it to be reused in other free software, but like to avoid deviant
versions of mine causing trouble.

I am not asking for money, but if you like and use it I would be surprised
and amazed by any contributions, and you will receive a disc with latest
versions on. (>£10, say)

Brian Brunswick                              [e-mail] (Internet)
Fairview                                  OR [e-mail]
Avenue des Hirondelles
Pool-in-WharfeDale
Leeds
LS21 1EY
UK
0532 843737

Versions later than 0.20:
========================

Because Brian is now out 'in the real world' I (Nick Smith) am acting as a
first line of support for !Virtual. I have tidied it up for the first public
release, and will improve the program as I get feed back from users, etc.
Currently, Brian wrote 90% of the actual software - so send him all that
money in gratitude !

Please email or snail-mail me comments, bug reports, requests for new
features, etc. and I will hopefully have the time to deal with them. If you
make any modifications to the code, please send them to me rather than
giving out copies - I would like to coordinate new releases. Thanks.

I can be contacted at the following address, at least until Jul '94 ;

N.A. Smith                                    [e-mail] (Internet)
Churchill College
Cambridge
CB3 0DS

Revision history:
================

Modifications to v0.21 (13-Mar-93) [ß-release]
  - !SwapDir resources application
  - Improved documention; added installation instructions, updated info,
    added revision history, etc
  - removed compilation dependency on having brian's harddrive 8-)
  - did some slightly better (but still awful) !Sprites, with !Sprites22
  - detailed *Help command provided
  - cleaned up code & file structure generally
  - cleaned up test/example software

Modifications to v0.22 (14-Mar-93) [release]
  - Made small number of changes that Brian asked for

Modifications to v0.23 (12-Apr-93) [release]
  - Bug reports showed that using pseudo-filing system Swap: was not
    RISC OS 2 compatible (really - people still use it!), so some
    very minor changes to use <Swap$Path>PageFile0 instead of
    Swap:PageFile0

Modifications to v0.24 (20-Apr-93)
  - Some more ideas for the 'ToDo' file
  - New SWI provided; Virtual_TaskInfo, like TaskWindow_TaskInfo
  - Some more SWIs supported including OS_Mouse, OS_SWINumberFromString,
    OS_ReadMonotonicTime and TaskWindow_TaskInfo
  - 'Bits.SWIs_list' file created - list of all supported SWIs
  - Better sprites for !SwapDir
  - Started work on !StartTask; a simple FrontEnd application that
    gives a 'friendly' user interface to the *Virtual command

Modifications to v0.25 (29-Jun-93)
  - Some useful bugfixes/contributed code from Ferdinand Oeinck ;
  - bugfix in MEMC page initialisation, now in FixMemMaps(), so that
    programs called from system() now return correctly. This was the serious
    problem that was stopping the Arc gcc compiler port from working!
  - Wimp_SlotSize SWI is now interpreted better
  - OS_Control, OS_ReadVduVariables, OS_SetVarVal, and OS_ConvertHex8 SWIs
    added
  - It is now possible to start Virtual in the Supervisor mode with the
    command ie 'Virtual "gos" -ctrl -wimpslot 3M'. When a program called
    from the prompt finishes, Virtual will stop, but you can get the prompt
    back by choosing 'Reconnect' from the Taskwindow menu.
  - Escape handling is now implemented, and works *most* of the time.
  - NOTE! This is an 'emergency' release to fix the gcc problems - lots more
    work will be done before the next release, hopefully mid-August.
    Some of the code new to 0.24 hasn't been finished/tested.

Modifications to v0.26 (02-Jul-93)
  - Another bugfix release - some more fixes from Ferdinand

Modifications to v0.27 (06-Jul-93) [release]
  - Some minor bugfixes, and a new gcc example makefile test for !Virtual
  - MAJOR bugfix for 16Kb pagesize (ie, 2MB RAM machines) *AT LAST* :-)
  - This version sent to Newcastle info-server

Modifications to v0.28 (09-Jul-93)
  - Problem with RISC OS 2 command parameters fixed
  - Now taskwindow compatible. Use *set alias$taskwindow "virtual %*0"
  - Mistake in hires sprites being defined in custom Mode 61 fixed
  - !VDump won't run under RISC OS 2, so now correctly checks the OS when
    loading, and exits cleanly under RISC OS 2.

Modifications to v0.29 (21-Jul-93)
  - Sent SWI chunk allocation request to Acorn Customer Support
  - Improved documentation on -pagefile, -txt, -task, -nice and -discslot
    parameters
  - Implemented Virtual_TaskInfo SWI
  - Implemented -discslot, and altered -wimpslot to physical RAM setting
  - Implemented -nice parameter for sceduling, controlling both timeslice,
    and delay to next wimp_pollidle
  - Fixed a problem with command parameters on subsequent OS_GetEnv (may
    have reintroduced RO2 problem :-(

Modifications to v0.30 (22-Jul-93)
  - Implemented DDEUtils_Prefix SWI handler (still broken :-(
  - Added appropriate code to deal with extended command lines from DDE
    FrontEnd tools
  - Added OS_Plot SWI

Modifications to v0.31 (23-Jul-93)
  - Finally sorted out !StartTask frontend application by using a 16 byte
    utility to call wimp_starttask on extended command line

Modifications to v0.32 (10-Aug-93)
  - Finally fixed problem with DDEUtils_Prefix - thanks Ferdinand!
    now fully compatible with Acorn DDE suite, just enable the *Taskwindow
    alias command in the !Run file and the DDE will use virtual taskwindows
  - Added details of taskwindow alias to !Help file
  - Noticed problem running !StartTask with Alias$TaskWindow set (a virtual
    task cannot be run from inside another virtual task currently) so we
    just ignore any !StartTask commands in this case

Modifications to v0.33 (16-Aug-93) [release]
  - New patch for an interesting SWI call ;-) Fixed mistake in xswis.h
  - Continuing problems with command parameters under RISCOS 2. It is
    unlikely that we can fix these in the near future - try getting RO3!
  - Stopped !StartTask from loading under RO2 - again, this won't be
    fixed
  - Saved a bit of memory by compiling virtual with -ff (no embedded
    function names)

Modifications to v0.34 (19-Aug-93)
  - Support added for OS_Byte, 129 call - required for some development s/w
  - Noticed that -quit/display/ctrl flags seem to be ignored completely!
    fixed up -quit so that it at least works(ish)
  - ShellCLI_TaskQuit didn't work (ignored) so built an alias for it so
    it works in both normal and virtual taskwindows
  - Support for Wimp_SendMessage SWI call

Modifications to v0.35 (24-Aug-93)
  - Got Acorn-allocated SWI chunk number :-)
  - Put together some ideas for the planned !Vmonitor application - but
    I'm not writing it!

Modifications to v0.36 (06-Sep-93)
  - Expanded on ideas for planned !VMonitor application
  - Deleted redundant poll.s and pager.s files from distribution
  - Added OS_File,0 and OS_File,10 SWI handlers, since some versions of
    squeeze (?) seem to require this
  - Added (c) messages to all source files
  - Removed 'Bits' module from inside !Virtual application
  - Pulled out all the #ifdef's for FIXED_SYSTEM_VERSION, TASKWINDOW_,
    etc - the new code works, so I've removed the old code completely
  - bracketed some more debugging messages with *ifdef DEBUG's

Modifications to v0.37 (07-Sep-93) [release]
  - Fixed the 'task input' code - not perfect, but works for all normal
    inputs, and doesn't crash
  - Tested on RISCOS 2 machine - text files reformatted for a Mode 12
    screen
  - ReBuilt 'Start' code for !StartTask - now uses new Virtual SWI chunk
  - Made a binaries-only distribution for a wider audience