WorldVM.mesa: raw access to client virtual memory
Copyright © 1985 by Xerox Corporation. All rights reserved.
Andrew Birrell September 20, 1983 2:25 pm
Russ Atkinson (RRA) February 6, 1985 9:11:40 pm PST
DIRECTORY
LoadState USING [ Handle ],
PrincOps USING [ op, BytePC ],
Rope USING [ ROPE ];
WorldVM: DEFINITIONS = BEGIN OPEN Rope;
This interface provides access to the VM on other machines running a teledbug server, and to the client side of a world-swap. Access to multiple clients is ok. The implementation takes care of the communication (or disk accesses), interpreting the client's MapLog, and a page-level (write-through) cache of the client's VM.
Part I: Obtaining a World
World: TYPE = REF WorldObject;
WorldObject: TYPE;
GetWorld:
PROC[where:
ROPE]
RETURNS[ World ];
Obtains "World" described by "where". "where" may be:
a Pup address constant, e.g. "3#14#",
a Pup NLS host name, e.g. "Cabernet",
a Grapevine individual name, e.g. "Cabernet.ms".
May raise "LookupFailed" or "BadWorld".
Returns when client responds to teledebug protocol.
OtherWorld:
PROC
RETURNS[ World ];
Returns "World" for the client side of a disk world swap of which we're the debugger side. May raise "BadWorld". First call of this causes us to outload and boot our physical volume; returns when we are inloaded. Subsequent calls just returns the same value.
LocalWorld:
PROC
RETURNS[ World ];
Returns "World" for our address space. All calls return the same value.
NoWorld:
PROC
RETURNS[ World ];
Returns an invalid "World".
InvalidateWorld:
PROC[ World ];
Makes "world" no longer usable; subsequent uses will raiss "BadWorld".
BadWorld:
ERROR;
Raised by VM access procedures if passed an invalid world;
Raised by "GetWorld" if the ROPE doesn't decribe a host;
Raised by "OtherWorld" if our system volume has type "normal".
LookupFailed:
ERROR;
Raised by "GetWorld" if communication with name lookup services failed.
Incarnation: TYPE = LONG CARDINAL;
CurrentIncarnation:
PROC[world: World]
RETURNS[ Incarnation ];
A world has an "incarnation". This is initialised to FIRST[Incarnation] and is incremented on each call of "Go[world]". The intention is to permit clients to detect out-of-date cached information.
WorldName:
PROC[ World ]
RETURNS[
ROPE ];
For remote worlds, returns the name given to "GetWorld". For disk world swap, returns "Outload". For local world, returns "Local".
Part II: Accessing the Virtual Memory of a world
The following procedures will each raise "BadWorld" if passed "NoWorld[]" or an invalid world as argument. In case of communication difficulties, they will retry indefinitely. Use Process.Abort to terminate if necessary.
Address:
TYPE =
LONG
CARDINAL;
General world-relative address
ShortAddress:
TYPE =
CARDINAL;
world- and MDS-relative address
Long:
PROC[world: World, addr: ShortAddress]
RETURNS[Address];
Lengthens a client MDS address.
AddressFault:
ERROR[addr: Address];
Raised by VM access procedures if address isn't mapped or if it's swapped out and the client has no MapLog.
Read:
PROC[world: World, addr: Address]
RETURNS[
CARDINAL ];
Reads (and caches) from World's VM
Write:
PROC[world: World, addr: Address, value:
CARDINAL];
Writes to cache and world's VM.
LongRead:
PROC[world: World, addr: Address]
RETURNS[
LONG
CARDINAL ];
Reads (and caches) double-word from World's VM
LongWrite:
PROC[world: World, addr: Address, value:
LONG
CARDINAL];
Writes double-word to cache and World's VM.
CopyRead:
PROC[world: World, from: Address, nwords:
INT, to:
LONG
POINTER];
Reads (and caches) block from World's VM
CopyWrite:
PROC[world: World, from:
LONG
POINTER, nwords:
INT, to: Address];
Writes block to cache and World's VM.
Part III: Breakpoint primitives.
IllegalPatch:
ERROR;
Raised by SetBreak or ClearBreak
SetBreak:
PROC[world: World, addr: Address, offset: PrincOps.BytePC]
RETURNS[oldByte: PrincOps.op];
PRIVATE: call only from AMEventsImpl
Set breakpoint in code segment, whose base address is "address", at
byte offset "offset", with bytes numbered as in PrincOps. Returns
previous contents of location. Raises IllegalPatch[] if there's already
a break there.
ClearBreak:
PROC[world: World, addr: Address, offset: PrincOps.BytePC, oldByte: PrincOps.op];
PRIVATE: call only from AMEventsImpl
Raises IllegalPatch[] if there is no break there.
Part IV: Allowing a remote or world-swap world to continue processing.
Lock:
PROC[world: World];
Increments a lock-count for this world. While the lock-count is > 0, the world
is not allowed the processor.
Unlock:
PROC[world: World];
Decrements the lock-count.
Go:
PROC[world: World];
PRIVATE: call only from AMEventsImpl
Primitive control transfer: allows world-swap or teledebug client to continue processing as soon as its lock-count comes down to 0. For world-swap, outloads us and inloads client, then returns when we are inloaded. For teledebugging, returns when client once again responds to teledebug protocol.
Part V: Finding the loadstate
This doesn't really belong here, but the loadstate address comes inside the ESV with the present protocols.
Loadstate: PROC[world: World] RETURNS[ LoadState.Handle ];
END.