General Points

DDT requires a domain key to do its job. The domain key may be provided to it explicitly. DDT may acquire the domain key in conjunction with the logic of the virtual domain keeper upon the first failure of a domain. Given a start key {or resume key} to a domain the domain's creator may be consulted to acquire a domain key {(iden)}. Given a start key to an OS style domain one should acquire the synthetic domain key by:
Getting a domain key to the OS domain with the aid of its domain creator,

Retrieving the domain's keeper {(get-dom-keep)}, which is an OS simulator,

Asking the simulator for a synthetic domain key {(getsyndk)}.

This would be more straightforward if OS domains were created by OS domain creators.

DDT is a machine language debugger that runs in another domain and interprets the symbol tables produced by our modified H assembler. See <ddtdoc,> for syntax and semantics of DDT.

DEBUG(0;PSB,M,SB,DOMAIN,SWITCHER,K19,DDTF==>c,str)
This call creates a DDT from DDTF passing it terminal keys from SWITCHER and the domain key DOMAIN. Key K19 (usually a directory key) will be accessable within that DDT as key slot 19.
c = 0 - All ok - str is null.

c = 1,2 - As from factory requestor's key

c = 3 - SWITCHER returned non-zero return code, rc. str is (4,rc).

c = 4 - DDTF did not follow extended jump protocol, return code rc was returned instead of kt+5. str is (4,rc).

c = 5 - DDTF returned non-zero return code, rc. str is (4,rc).

DEBUG(kt==>X'2080D')

DDTF(0;PSB,M,SB,SIK3,SOK3,CCK3,D,K19 ==> c;) "Create DDT"
This call uses the extended jump protocol (p3,ejp).

This operation creates a DDT and starts it operating on domain D. M is a meter. The DDT will use the terminal defined by SIK3, SOK3, and CCK3. (SIK4, SOK4, and CCK4 keys will also serve this purpose.)

D must be a domain key with C3 rights. The domain is initially considered active (i.e. DDT holds no resume key to it).

The key K19 will be installed as the initial value of key index 19. This key will be available for any purpose through the KEY command, so it represents the authority that the terminal user should have.

The following convention has been proposed for that key: It is a node or super-node with the following slots defined:
Slot 0: a meter key

Slot 1: a prompt space bank

Slot 2: a space bank

Slot 3: a switcher

Then a DDT command could, given a domain key, build another DDT over it using the resources in slot 19.

The key in C10 of the domain {to the symbol table} will be installed in key index 20 (where the ";T" command will use it).

Possible return codes c are as follows. In the current implementation, if a nonzero code is returned the state of things is not necessarily put back the way it was before the attempt.

0 - successful. A new domain keeper and meter have been installed in the domain.

1 - PSB is not a prompt official space bank.

2 - not enough space in PSB.

3 - not enough space in SB.

5 - D is not a domain.

6 - SB is not an official space bank.

8 - the order code is nonzero.

DDTF(kt;==> X'1080D';).

{See (getsyndk) about getting an appropriate domain key for an os object.}

PDDTC(0;PSB,M,SB,SIK3,SOK3,CCK3,D,K19,PEEK ==> c;) "Create Peek DDT"
Similar to "Create DDT" (ddtf0).

The DDT will use PEEK (see (p2,peek)) to reference "memory", rather than slot C3 of the domain. {Any other key that behaves as peek for order code 0 is valid in place of PEEK.}

PDDTC(kt;==>c;) returns X'C0D' in c.

VDKC(0,SB1,M,SB2,RC) ==> c,VDK) "Create VDK of the silent type"
This operation is obsolete. Use (vdk2rcf) instead.

This use extended jump protocol (p3,ejp).

This operation create a virtual domain keeper and returns it as VDK. When a domain with VDK as its keeper traps, a record is written in the RC record collection with the TOD as the name (in TOD format) and the DOMAIN key of the trapping domain as the key in the record.

To debug this domnain, build a DDT over the domain (the DEBUG command in the old command system) and user the RESET;; command to get control of the domain (the restart key was discarded), and ;S will cause the domain to report the trap code.

If the trap was for an invalid meter, then slot 2 of the domain is tested to see if it is an exit key. If it is then it is forked with KT+10 and the domain key is not recorded in the record collection.

VDK must be called as follows VDK(347;CLOCK ==>c) to supply a CLOCK key to time stamp the record in the record collection. VDK crashes if it doesn't have a clock key.

VDKC(1;SB1,M,SB2,SWITCHER,DDTFACIL ==> c;VDK) "Create VDK from switcher"
This uses extended jump protocol {(p3,ejp)}.

This operation creates a virtual domain keeper and returns it in VDK. VDK may be used as the domain keeper in one or more domains. When a domain with VDK as its keeper traps, a new branch of the switcher is created and a DDT {(ddt)} is created to debug that domain, using the new branch. (There is no relationship between the name of the branch and the domain.) C10 of the domain contains SYMSEG, a memory key defining up to a megabyte of symbol table. Note: the use of SYMSEG may change. See (p3,wombfacilresdomkeep) about a standard such VDK.

The key DDTFACIL will be available to the DDT as key index 19.

SB2 is a space bank. M is a meter. c=0 if successful, 1 if SB1 is not a prompt official space bank, 2 if not enough space in SB1. If some other error occurs, ...

VDKC is in SYS. and the womb too {(p3,wvdkc)}.

VDKC(kt;==>X'A0D';).

VDK(kt;==>X'10A0D';).

VDK2RCF(0;SB1,M,SB2,RC) ==> c;VDK2RC) "Create VDK2RC"
This use extended jump protocol (p3,ejp).

This operation create a virtual domain keeper and returns it as VDK2RC.

VDK2RCF(kt;==>X'20A0D';).

VDK2RCF is in SYS. and the womb too {(p3,wvdkc)}.

VDK2RC(kt;==>X'30A0D';).

When a domain with VDK2RC as its keeper traps, a record is written in the RC record collection with the TOD as the name (in TOD format) and the DOMAIN key of the trapping domain as the key in the record.

To debug this domain, build a DDT over the domain (the DEBUG command in the old command system) and use the RESET;; command to get control of the domain (the restart key was discarded), and ;S will cause the domain to report the trap code.

If the trap was for an invalid meter, then slot 2 of the domain is tested to see if it is an exit key. If it is then it is forked with KT+10 and the domain key is not recorded in the record collection.

{arcane}{ni}DDT Desiderata

The following set of tools should be available as a tool kit within DDT. They should be packaged to be used conveniently by the DDT user but not so as to be unavailable to other programs.

A record collection indexed on alleged key type that leads to a short description of the key along with an Augment label referring to the documentation.

A meter tester. It would (by running a test domain) determine if a key is either:

Not a meter key,

A meter key to an invalid meter,

A meter key to a valid meter with no juice, or

A good provident meter.

Domain Diagnostics
This is a collection of ideas about a service provided by some domain that takes a domain key and non-destructively tests it and returns the results.

This is like the mythical domain server {(p1,domserv)}. While it doesn't execute the domain it gives an extensive excuse if the kernel would find some reason for not running the program.

Its natural caller would be DDT but other programs might find it useful.

Enumeration of tests

Quality of meter: The meter of the domain would be classified into one of four progressively more suitable categories:
Mot a meter key.

A meter key to a node that is not a meter. By this I mean that there is no chain leading to the primordial meter. This can be discerned by the fact that any process in a domain under that meter disappears. (This state may be indistinguishable from the next state!)

Meter valid but exhausted. (When other resource counts are implemented in the kernel this category must be expanded.)

Meter can produce headway.

The PSW would be examined for validity including evenness.
This might be a mistake because this function overlaps the kernel's function.

If the domain can't issue SVC's a note is made.
This too might be wrong, there being nothing intrinsically wrong with being unable to issue SVC's. Someone must do this and DDT already does.

The Trap code is examined for nonzero.
Again, this might be beyond the scope of explainer since this fact is presumably brought to the attention of the domain keeper by the kernel.

This leads to the next point.

The keeper of the domain (the key form C2) is compared for equality with a key parameter provided by the caller of explainer. This is to detect the replacement of the domain keeper via some unauthorized domain key. (Presumably a domain keeper should be the only holder of the domain key to the subject domain.)

The domain's address segment and PSW is examined to determine whether an instruction could be fetched. This involves an attempt to access the domain's segment. We use a kamakazi domain for this.

The domain's segment is tested for accessibility of the operands.

Store type operands are tested with the CS instruction in a way to verify writability without writing.

Existence of process: The following test tends to indicate whether there is a process in the domain. {Perhaps we should change the kernel to provide any information here that can't be hidden from stuff like this.}
Install a valid meter to an exhausted meter.

Install a page key to a page with a SVC 0 at 0 as the domain's segment.

Install a PSW that designates the instruction at address 0.

Install a valid meter with CPU resources.

Install the Never key as the domain's keeper

Issue {unimplemented} domain key call to remove domain from stall queues if that is where it is at.

Observe whether PSW changes.

Install exhausted meter.

Put back original PSW, segment, keeper and then meter.

It would be nice if one could ask DDT to reinterpret the trap code of its domain. It now interprets it well as the trap code is produced but it won't help you if you forget what it told you. Perhaps the "%h" command could do this -- then again that is a kludge.