-- Cedar Remote Debugging: raw access to client virtual memory

-- WorldVM.mesa

-- Andrew Birrell September 1, 1982 3:03 pm

DIRECTORY
Mopcodes    USING[ op ],
PilotLoadStateFormat USING[ LoadStateObject ],
PrincOps     USING[ BytePC ],
Rope      USING[ ROPE ];

WorldVM: DEFINITIONS =

BEGIN

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


World: TYPE = REF WorldObject;

WorldObject: TYPE;



GetWorld: PROC[where: Rope.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.ROPE ];
-- For remote worlds, returns the name given to "GetWorld". For disk
-- world swap, returns "Outload". For local world, returns "Local".


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


-- Breakpoint primitives. These should only be called from ClientActionsImpl.

IllegalPatch: ERROR;
-- Raised by SetBreak or ClearBreak

SetBreak: PROC[world: World, addr: Address, offset: PrincOps.BytePC]
RETURNS[oldByte: Mopcodes.op];
-- 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: Mopcodes.op];
-- Raises IllegalPatch[] if there is no break there.


-- The following procedures are concerned with 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];
-- 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.
-- NOTE: this procedure should be called only by ClientActionsImpl. --


-- This doesn't really belong here, but the loadstate address comes inside the ESV
-- with the present protocols.

Loadstate: PROC[world: World] RETURNS[ REF PilotLoadStateFormat.LoadStateObject ];

END.