Figure 2-13C6, which must be a data key, defines which classes of the monitor call instruction are to be enabled. The monitor mask bits are the low order 16 bits of the data key, which correspond to monitor classes 0 to 15, respectively. If a bit is one then the corresponding class is enabled and a monitor call instruction specifying that class will cause a trap. The rest of the data key is reserved and must be zero.
C7 through C9 control program event recording if bit P in C4 is on. Otherwise, they do not influence the process in the domain.
Figure 2-13
The right 48 bits of the values of the data keys in C7 and C8 define the program events in BISG (successful branch, instruction completion, storage alteration, and general register alteration respectively), the start address in ssss ..., and the end address in eeee ... For further information see the Program Event Recording section of IBM System/370 Principles of Operation.
When a program event occurs, C9 receives a data key. The low six bytes of data contain, in the high two bytes, the PER code (returned in locations 150 and 151 by the 370 hardware) and, in the low four bytes, the PER address (returned in locations 152 through 155 by the 370 hardware). The rest of the data key is unspecified.
When a program event occurs, the trap code for the event, as well as other possible simultaneous traps, is placed in C5. See the section in this chapter entitled, "Trapping".
Programming note: The PER facilities as they appear to the KeyKOS user are transformed somewhat from how they are described in the IBM System/370 Principles of Operation. A program event detected in the execution of an instruction causes setting of C9 and the PER bit in the trap code only once per (conceptual) execution of the instruction. This setting occurs after the event has occurred and before any new instruction in that domain has started. (It may occur before the end of execution of the instruction that produced the event.) Thus, the instruction fetch event may not be reported until the instruction concludes.
An explicit key invocation is the event that occurs in a domain, beginning when the domain executes a CALL, RETURN, or FORK invocation, and ending when the domain is about to execute the next instruction.
For purposes of program event recording, an explicit invocation is treated as an instruction. The instruction fetch event will occur at the end of the instruction just as if the invocation had been an ordinary instruction. If a register is altered and that register is being monitored for alteration, the register alteration event will occur. (FORK invocations do not modify registers.)
Implicit invocations do not cause program events; key invocations do not cause successful branch events.
When the parameter string of the invoked domain is specified by its virtual address, a storage alteration event may occur in the invoked domain. The event will occur only if some portion of the parameter string is being monitored for alteration.
It is implementation dependent whether storage of the byte string in only the portion of the parameter string that is not being monitored causes a program event.
The following detail explains some other side effects of PER and explicit invocations. This detail is necessary only to explain the consequences of using a domain key to a calling domain.
When any of certain events occurs in a domain (typically unanticipated by the program of the domain) the kernel places a non-zero data key, called the trap code, in C5 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.)
A domain is trapped when a non-zero trap code is introduced. Since this action, by itself, does not set the domain's process-running bit TRUE, an implicit invocation to the domain keeper will not automatically follow the setting the trap code.
Whenever the domain's process-running bit is TRUE and the trap code is non-zero, an implicit invocation (called a trap) of the key in C2 (called the domain keeper key) will occur before the domain takes any other action. Since this is an implicit invocation, the domain keeper key should be a gate key to another domain, called the domain keeper, or the Error Key. The parameters passed are:
The low six bytes of the data key in C5 are the trap code. The bytes are numbered from 0 through 5, from left to right. All other bytes are zero.
Figure 2-14
Byte 0 of the trap code, (called "TC0"), describes the general type of trap. A program event sets bit 4 of TC0 to 1. A program event occurring at the same time as one of the traps described below will cause TC0 values of 8 through 15. A program event occurring alone sets bytes 2 through 5 to zero.
TC0 = 0: A process in the domain encounters one of the program interruption conditions listed below.
Figure 2-15
"Instruction length" is 2, 4, or 6. (The instruction length code cannot be zero.) "Interrupt code" is described in Figure 2-16 below. The operation is completed, suppressed, or terminated, as indicated by the IBM System/370 Principles of Operation.
Figure 2-16
Design note: Since program interrupt code 0 is never generated, the abridged trap code passed to the domain keeper will never be equal to X'80000000', the parameter word for the alleged type convention.
TC0 = 1: A monitor instruction is issued by a domain that specified a 1 bit for the appropriate monitor class in C6 of the domain root.
Figure 2-17
"Mon class" is bits 8 through 15 of the monitor call instruction (the monitor class number). "Monitor code" is the monitor code. (The instruction length is 4.) The instruction execution is completed.
TC0 = 2: Rejected parameter word.
Figure 2-18
TC0 = 3: The domain executed a SVC and LL of the domain's C4 was 00, or LL of C4 was 03 and the SVC code was not 253, 254, or 255.
Figure 2-19
"SVC code" is the interrupt code (right eight bits of the SVC instruction). "Instruction length" is 2 or 4. The instruction execution is completed.
TC0 = 4: The domain encountered an addressing fault at a virtual address for which there was no defined segment keeper key.
Figure 2-20
"Error code" is the error code as summarized in Figure 2-11 entitled "Error Code Summary". "Offending address" is the address that was applied to the domain's addressing segment key. The unit of operation is nullified.
TC0 = 5: The domain attempted an invocation with invalid parameters or depended on an invalid meter.
Figure 2-21
The following two tables (Figures 2-22 and 2-23) describe the meanings of Class code and subcode when TC0 = 5:
Figure 2-22
Figure 2-23
TC0 = 6: The domain attempted an invocation in which the domains involved in the invocation have nodes which overlap in certain unsupported ways.
Figure 2-24
In this discussion, "returnee" refers to that domain designated by the resume key provided as the fourth key parameter of the CALL invocation. The instruction execution is nullified.
Figure 2-25
Design note: This trap code can be prevented by restricting the domain tool key to programs that will not allow overlapping domains to be built.
TC0 = 7: A gate key to the domain was invoked with a string argument, but some required portion of the parameter string was at an address for which the addressing segment provided a read-only page or no page. The invoked domain's instruction execution is suppressed.
Figure 2-26
"Error code" is the error code as summarized in Figure 2-11, "Error Code Summary". "Offending address" is the address that was applied to the domain's addressing segment key.
Programming Note: Between setting the trap code and invoking the domain keeper key, other programs may run.
Programming Note: If the action was an invocation and the fault did not involve the invoking domain, the state of the invoking domain at the conclusion of the invocation will be as if there had been no fault.
Design Note: 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 action 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 the domain's process-running bit is FALSE. This situation can occur when an invocation is made to a domain with an invalid parameter page key and an entry block that rejects the parameter word. It is implementation dependent which trap code will be stored in these cases.