The Datafile PD-CD 4/DATAFILE_PDCD4.iso/utilities/utilst/virtual/!Virtual/!Help

Text File | 1993-07-06 | 10.9 KB | 231 lines

!Virtual 0.27
=============

!Virtual supplies virtual memory under RiscOS 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 very restrictive in what can be done - basically
only simple line based programs can be used. This is quite sufficient to run
C compilers, though, which is what I wanted it for. If you want to do
anything more than that with it, you will need to get pretty technical.

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 RiscOS swi calls run in supervisor mode. On the ARM2/ARM3 a prefetch or
data abort corrupts svc_R14, and RiscOS 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 RiscOS, and should really be thought of as
running under a different operating system, that just happens to be hosted
on RiscOS.

At the moment, I have implemented only the swis I have found necessary to
run things. See the file 'Bits.SWIs_list'.

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 -wimpslot 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.

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 "/", are specially treated, to
allow the running of executable files that are bigger than the real WimpSlot
that virtual posesses

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
RISCOS. They have access to a very limited subset of particular swis that
I've implemented properly. Further swi routines accepted with enthusiasm - I
don't really have the time or energy to do them myself.

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 - can you help?"

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 RISCOS,
  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 99.5% 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) [Beta-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
    RISCOS 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) [internal]
  - 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) [internal]
  - 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) [internal]
  - 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