UP

General Points

When any of several certain events occur in a domain {typically unanticipated by the program of the domain} a nonzero value, called the trap code, is placed into component five of the domain to indicate the nature of the event. {A domain key or node key may also be used to set the trap code.}

When a domain D attempts to run while its trap code isn't zero, an implicit call is made to another domain called D's domain keeper. The domain keeper is in a position to examine the cause of the problem. This call is normally an immediate consequence of setting the trap code.

C2 of a domain is the domain keeper key for that domain.
The domain keeper key, DKK, is implicitly jumped to when there is a process in the domain and the trap code {(p1,trapcode)} is not zero.

The jump is: JUMP DKK(Atc;,,DK,EX) where:

"Atc" is an abridged trap code consisting of 1 in bit 0, followed by bits 1 thru 7 of the full trap code, followed by bits 24 thru 47 of the full trap code. {This information will suffice in many cases.}
Programing Note: It is a design goal never to generate an Atc which is equal to kt {(p3,alleged)} with an implicit jump. This allows entries designed as domain keepers to respond to "kt" calls.
DK is a domain key to the trapped domain.

EX is a restart key to the trapped domain.

At the conclusion of the jump there will be no process in the trapped domain. {The trapped domain will be busy.}

{If C2 is a start key, the domain it designates acquires the capabilities of the trapped domain and must be completely trusted.}

C5 is a data key. Its low 6 bytes are the trap code.
The bytes of the trap code are numbered from 0 thru 5, from left to right with 5 being the rightmost byte of the value of the data key. Bytes of the trap code that are not otherwise described in this section are zero. In this section "TC0" refers to byte 0 of the trap code.
TC0 = 0. A process in the domain encounters one of the program-interruption conditions listed below.
The instruction length {2, 4, or 6} is placed in bytes 2 and 3. {The instruction length code cannot be zero.} The interruption code is placed in bytes 4 and 5 of the trap code.

The operation is completed, suppressed, or terminated, as indicated by POP.

The possible program-interruption exceptions and their interruption codes are:

1 Operation

2 Privileged-Operation

See (sm) about some circumstances where a privileged instruction will not produce a trap code.
3 Execute

6 Specification

The following causes are possible: odd PSW; non-integral operand boundary {CS, CDS, or EX}; odd register {CLCL, MVCL, CDS, Multiply, Divide, and double shifts}; invalid floating-point register; decimal multiply/divide errors; invalid MON instruction.

Another reason may be added: Bits 16 thru 23 of the data body of C4 {the PSW} are not zero. See (bigiaok).

7 Data

8 Fixed-Point-Overflow

9 Fixed-Point-Divide

10 Decimal-Overflow

11 Decimal-Divide

12 Exponent-Overflow

13 Exponent-Underflow

14 Significance

15 Floating-Point-Divide

{arcane}Note that since program interrupt code 0 is never generated the abridged trap code passed to the domain keeper will never be equal to kt.
TC0 = 1. A monitor instruction is obeyed by the domain which specifies a one bit of the control field given in C6 of the domain root. {See (p1,d6).}
Byte 1 is set to bits 8 thru 15 of the monitor call instruction {the monitor class number}. Bytes 2 thru 5 are set to the monitor code. {The ILC is 2.}

The instruction execution is completed.

TC0 = 2. Rejected return code. See (p1,jtrap). The rejected nonzero order code is in the right 4 bytes of the trap code.

TC0 = 3. The domain obeys an SVC and (bits 8 thru 17 of C4 are 00, or bits 8 thru 17 of C4 are 03 and the SVC code is not 253, 254, or 255).

The interrupt code {the right 8 bits of the SVC instruction} is placed in byte 5 of the trap code.

The instruction length code {1 or 2} is placed in bit positions 5 and 6 of byte 3, with byte 2 and the rest of byte 3 set to zero.

The instruction execution is completed.

TC0 = 4. The domain encounters an addressing fault at a virtual address for which there is no defined segment keeper key. See (p1,adrtrap).
The error code {(p1,err-codes)} is placed in byte 1 and the offending address is placed in the right 4 bytes of the trap code.

The unit of operation is nullified.

{tentative}TC0 = 4. The domain encounters an addressing fault. See (p1,adrtrap) and (p1,fault-act).
The offending address is placed in the right 4 bytes of the trap code. If the access was a write and the segment does not provide write access, byte 1 is set to hex 80, otherwise 00.

The unit of operation is nullified.

TC0 = 5. Byte 4 distinguishes the following classes:
Byte 4 = 0. Jump at fault: Byte 5 holds a sub-code:
Sub-code = 0: a domain attempts a jump to a gate key to the domain itself. The instruction execution is nullified.

{arcane}Sub-code = 2: Bits 4 & 5 of an exit block are 10. The instruction execution is nullified.

Sub-code = 4: Invalid entry block format.

Sub-code = 8: parameter string called for in registers {(regparm)} but invalid parameter string specification for registers. Registers 4 and 5 fail to specify a parameter string that is entirely within the registers. R4+R5 exceeds 96.

Sub-code = 9: argument string specified as originating in registers {(regparm)} but invalid extent. Registers 2 and 3 don't specify an argument string that is entirely within the registers. R2+R3 exceeds 96.

Byte 4 = 1. Invalid meter. Byte 5 holds a sub-code described at (badmeter).

Byte 4 = 2. BC mode PSW simulated {bit 8 of PSW is on} and one-bit at 12, 14 or 15 of simulated BC mode PSW. See (sm).

Byte 4 = 3. Bits 8 thru 17 of C4 are neither 00 nor 03 or bit 0 of C4 is 1.

{arcane}TC0 = 6. The domain attempts one of a class of invalid jumps. {These codes cannot occur unless there are bad programs holding domain-tools.} In this section the term returnee refers to that domain designated by the resume key provided as the last key parameter of the jump. {The returnee is usually the jumper.} The instruction execution is nullified. Byte 5 holds a sub-code SC:
SC = 4. The jump was to a gate key which designates the jumper's general keys node or general registers node.

SC = 5. The jump was to a gate key and the jumpee shares nodes with the jumper.

SC = 20. The jump was a return or fork to a primary key and the returnee's domain root is the jumper's general keys node or register node.

SC = 21. The jump was a return or fork to a primary key and the returnee's domain shares nodes with the jumper's domain and the returnee's domain root is distinct from the three nodes of the jumper.

SC = 36. The jump was to a domain key and the invoked domain's root is the jumper's general registers or general keys node.

SC = 37. The jump was to a domain key and the invoked domain shares nodes with the jumper's domain and the invoked domain's root is distinct from the three nodes of the jumper.

SC = 48. The jump was to a node key to the returnee's domain root and the order code was 30, 31, or 45, or the jump was to a domain key and the invoked domain's general keys node is the returnee's domain root, and the order code was 62 or 63.

SC = 49. The jump was to a node key to the returnee's general register node, and (16 <= the order code < 32 or order code = 45), or the jump was to a domain key and either {1} the invoked domain's root is the returnee's general register node and 32 <= order code < 48 or order code = 73, or {2} the invoked domain's general keys node is the returnee's general register node and 48 <= the order code < 64.

SC = 50. The jump was to a segment key and the segment node is the jumper's domain root or general registers node.

SC = 51. The jump was to the DOMAIN_TOOL with order code 1, 2 or 3 and the root node of the domain whose brand is to be checked is the jumper's general register node.

TC0 = 7. A process entered this domain with a string argument but some required portion of the parameter string was at an address for which the memory tree provided a read-only page or no page. See (p1,parmcall). The {jumpee's} instruction execution is suppressed.
The error code {(p1,err-codes)} is placed in byte 1 and the offending address is placed in the right 4 bytes of the trap code.
{ni}TC0 = 8. Damaged domain or node operand.
I am disinclined to implement this until we see at least one strategy that benefits hereby. The more common disk damage report described at (bad-page) supports known strategies that promise real benefits.

{The choice of 8 conflicts with PER.}

In the meantime, this section may serve either to guide the design of damaged node strategies or may suggest some other way of reporting damaged nodes.

Sub codes would be assigned during implementation. We list here the events that we think that we will be able to distinguish:

Damaged domain root, Damaged keys node, Damaged regs node, Damaged node operand {referee of node or fetch key},

Damaged segment nodes would presumably be reported as an erroneous memory reference with code 12, and then only if a segment keeper was not about to take the report.

An alternative to this general scheme might be to notify a space bank when some of its space was damaged. The bank might be in a position to cause the replacement of some larger apparatus. Getting node damage reports via domain keepers may be difficult to debug and may, in fact, have little to do with the other {natural?} functions of the domain keeper.
{arcane}If a program event occurs, bit 4 of TC0 is set to 1. A program event occurring at the same time as one of the conditions described above will therefore give rise to values of TC0 of 8, 9, 10, 11, 13, and 15. {Nullified operations do not cause program events.} If a program event occurs alone, bytes 4 and 5 will be zero but bit positions 5 and 6 of byte 3 may be set to garbage. See also (p1,progevents).

If KVMA is active {bit 8 in PSW} and the logical and of the pending interrupt mask and the system mask is not zero then bit 3 of TCO is turned on.

A domain is said to be trapped when a nonzero trap code is introduced. {Any action that causes a nonzero data key to be placed in C5 will have the same effect.} {Since such an action by itself does not introduce a process into the domain, the implicit jump to the domain keeper will not follow by virtue of trapping the domain. If there is a process already in the domain the trap will occur. If a process enters the domain while the trap code is still not zero the process will trap before any instructions of the domain are executed.}

{arcane}Design Note
When the kernel discovers that a program must suffer a trap, the keeper's domain is required for further action. After this discovery and before the keeper's domain is brought to main storage, other programs may run. If these other programs enquire about the state of the trapped program they will find that it has a nonzero trap code. The reason for the trap is remembered in the trap code C5.
{arcane}Program Notes
If the action was a jump and the fault did not involve the jumper then the state of the jumper at the conclusion of the jump will be as if there had been no fault.

Normally the setting of the trap code by the kernel replaces DK(0). This is not always the case. Since a domain can take no actions other than to trap when the trap code is not zero, these situations occur only when one action causes two trap codes to be produced, or when a trap code is produced when there is no process in the domain.

This situation occurs when a jump is made to a domain with an invalid parameter page key and an entry block that rejects the order code.