How a Domain Invokes a Key

During a gate invocation, the process running-bit may become false in one domain and will become true in a second domain. The second domain will start running immediately after the first has stopped.

Parameters

• Data Parameters - Two data parameters are passed: a 32-bit parameter word and a byte string. The byte string is a variable length sequence of from 0 to 4096 8-bit values. The invoking domain program specifies it as the argument string. An invoked domain receives it as the parameter string.
• Key Parameters - Four keys are passed.

Types of Invocations

• Explicit Invocation - A domain invokes a key explicitly by issuing one of three SVC instructions with bits -34 and -33 of its C4 both one. It specifies what parameters are to be passed with an exit block and, if it expects to be re-entered after the invocation, it specifies where parameters are to be received with an entry block.

  CALL (SVC 253) - The invoking domain enters the waiting state (i.e., its process-running bit becomes FALSE). The last key parameter passed is always a newly created (by the kernel) return key to the invoking domain. In anticipation of that return key being invoked (by some other program), the domain normally loads an entry block before executing a CALL.

  RETURN (SVC 254) - The invoking domain's process-running bit becomes FALSE and the domain enters the available state. In anticipation of some start key to this domain being invoked (by some other program), the domain normally loads an entry block before executing a RETURN.

  FORK (SVC 255) - The invoking domain remains running. Since it remains running, no entry block is loaded.

• Implicit Invocation - Several events in a domain cause implicit invocations. These events are described in sections in chapter 2 entitled, "Meters, Resources, and Charge Sets", "The Addressing Segment and Virtual Addresses", and "Trapping".

  In an implicit invocation, the CALL invocation is simulated by the kernel, loading an entry block which specifies no keys, a zero parameter word, and a zero length parameter string. The invoking domain enters the waiting state and a resume key is created by the kernel and passed as the fourth key parameter.

  The invoked key must be a gate key or the Error Key. If it is not, the implicit invocation does not take place and the invoking domain is left in the waiting state.

Specifying an Explicit Invocation

Figure 2-4

The invoking domain specifies the parameter word by loading it in general register 1.

If AA is 00, a zero length byte string data parameter is provided.

If AA is 01, general registers 2 and 3 specify the address and length respectively of the byte string data parameter. The length, in register 3, is considered as a 32-bit unsigned integer. The length must be less than or equal to 4096. If it is not, the trap code is set with TC0 = 5 and subcode 6.

If AA is 10, the trap code is set with TC0 = 5 and subcode 2.

If AA is 11, general registers 2 and 3 specify the address and length of the argument string within the registers. For this purpose the 32 bytes of floating registers 0 through 6 are considered to follow and be contiguously adjacent to the 64 bytes of the general registers.

Figure 2-5

For i from 1 through 4:

• If the ith bit of MMMM contains a 1, the ith key argument is the key in the invoking domain's key register specified by the ith slot number, KKKK.
• If the ith bit of MMMM contains a 0, the ith key argument is DK(0).

Invocation Action

Step 1

The key to be invoked is identified and the four key parameters are (conceptually) copied to a temporary area.

If the key being invoked is a resume key, all copies of it become DK(0).

The state of the invoking domain is adjusted according to the type of invocation (CALL, RETURN, or FORK) and its instruction address is advanced to the next sequential instruction.

Step 2

The key is invoked with the parameters from the temporary area. With two exceptions, Step 1 is (conceptually) completed before Step 2 is begun. Step 1 is the same regardless of what key is being invoked or what the parameters are, and Step 2 is the same regardless of the invoking domain or its state. This means that effects flow only from the invoking domain to the object designated by the invoked key and not in the other direction. The exceptions are:

• Certain I/O keys implemented in the kernel.
• Stalling - This means that execution of the invoking domain is suspended just before Step 1. When the reason for stalling ceases, execution invocation, it is still in the running state with its PSW addressing the invocation instruction. A stalled domain consumes very few resources.

The invoking domain will stall until all pages and nodes needed to complete the invocation are in main memory.

In some implementations, a FORK invocation of a gate key may stall when establishing the new domain as "process-running" would exceed a process-running limit built into the kernel. In this case, the kernel may call the decongester to help. The domain issuing the FORK need not be aware of this.

If a start key is specified and the designated domain is busy, the invoking domain stalls. If the invoking domain is still at this point when the busy domain becomes available, the invocation will then proceed.

Some implementations may not recognize that the situation leading to the stall has changed in some way other than the invoked domain becoming available. In these implementations, the invoking domain will not proceed until the invoked domain becomes available or some other implementation-defined event occurs. Thus, if the invocation instruction that had caused the explicit invocation were changed to a NOP, the invoking domain would remain stalled despite its process-running bit being TRUE and the lack of an obstacle.

Normally, stalled invoking domains are restarted in the order that they became stalled. This is not always possible.

All the action of invoking a key depends on (uses the resources of) the meter of the invoking domain.

Design note: It might seem reasonable for a version of KeyKOS to provide buffering to avoid stalling. In this case, the invoked key and parameters would be held in a message and the disposition of the invoking domain would occur immediately. For example, a domain executing a FORK of a start key to a busy domain could find that the FORK completes (i.e., the domain goes on to the instruction after the FORK) while the action of invoking the start key has not yet occurred. This has not been implemented because of the difficulty of accounting for and limiting the storage required for the messages.

Gate Types

There are two types of gate keys:

• Start keys are somewhat like the Fortran ENTRY concept, and even more like the PL/1 construct by that name. Start keys may be used only to give control to an available domain.
• Resume keys are produced with the CALL or implicit invocations to allow return to the invoking domain. Resume keys may be used only to no resume keys to available or running domains.)

All resume keys to a given domain are replaced by DK(0) when any one of the them is invoked; therefore, a resume key can not be used more than once.

There are three kinds of resume keys:

• Return keys are produced during an explicit CALL invocation. Return keys may be used to return control to the domain that executed the CALL.
• Fault keys are produced during implicit invocations of segment keepers. A fault key may be used to restart the domain it designates, or to trap it (by offering a non-zero parameter word), but not to pass any other parameters.
• Restart keys are produced during implicit invocations of meter keepers or of domain keepers. A restart key may be used to restart the domain it designates, but not to pass parameters. A non-zero parameter word will be ignored.

Programming note: When a resume key is invoked with a RETURN, the parameter word is frequently called the return code.

How an Invoked Domain Receives Control

A domain program provides an entry block to indicate which parameters to accept and where to accept them when an invocation makes the domain's process-running bit TRUE. The entry block specifies the conditions that the program logic expects as the invoked domain begins running after an invocation. The type of invocation and the related exit and entry blocks determine invocation action between domains.

If the invoked key is a start or return key, the entry block for the invocation is taken from floating register 2 of the invoked domain.

If the invoked key is a restart or fault key, the entry block will be X'10000000' (no parameters are accepted).

The format of the entry block is:

Figure 2-6

If C = 1 then the parameter word will be placed in general register 1 of the invoked domain. Otherwise, register 1 is unchanged.

If S = 1 then general register 4 holds the address (in either the invoked domain's virtual memory or its registers) of the parameter string, and register 5 holds the maximum length of the parameter string.

If L = 1 then the length of the argument string will be placed in general register 3.

If the argument string is shorter than the maximum length specified for the parameter string, values beyond the length of the argument string will remain unchanged. If it is longer, the remainder of the argument is not transmitted.

If R = 0 then the parameter string is in the invoked domain's virtual memory.

If R = 1 then the parameter string is in the invoked domain's registers. For this purpose the 32 bytes of floating registers 0 through 6 are considered to follow and be contiguously adjacent to the 64 bytes of the general registers (see Figure 2-5).

If some of the parameter string is in a page that is not defined read/write in the invoked domain's addressing segment, and some part of the argument string is to be placed in that page, then an addressing trap code will be produced in the invoked domain even when a write reference to that address by a problem mode instruction in the invoked domain would have caused a call invocation to a segment keeper. No segment keeper will be called. It is as if the reference to the parameter string had been made via a memory key with a no-call bit. In this case the portion of the argument that was to have been copied into that page is not copied but the rest of the invocation action proceeds.

If S = 0 then the argument string is not accepted and R and L are ignored.

If D = 1 then general register 2 of the invoked domain is set to a value determined by the gate key. If the gate key is a start key, the value is the data byte of the start key with 24 high order zeros. If the gate key is a resume key, the value is zero.

For i from 1 through 4:

• If the ith bit of MMMM contains a 1, the ith key parameter is received and placed in the key register specified by the ith slot number, KKKK.
• If the ith bit of MMMM contains a 0, the ith key parameter will not be received (and the corresponding slot designator KKKK will be ignored).

Trapping Due to Rejected Parameter Words

When the parameter word is not 0 and the gate key is not a Restart key, and bit C in the entry block is 0 then after the key parameters and other data parameters have been passed to the invoked domain, and before it enters the running state, the first byte of the invoked domain's trap code is set to 2 and the invoking domain's parameter word is placed in the right four bytes of the invoked domain's trap code. The normal trap action then takes place.

Pathologies

The following paragraphs describe some states that were not designed to be useful, but are not prevented.

• Exceptional Invocations - If a resume key is used to an available domain (this may occur if a node key to a domain root is used to change C13), the effect upon the invoking domain is as if the invoked domain had been busy. If an invocation is made to a malformed domain, the effect upon the invoking domain is as if the invoked domain had been well-formed. There is no effect upon the invoked domain. No resume keys are deleted.

  If a return key to a running domain is invoked, the arguments may be deposited in the invoked domain (according to the invoked domain's current entry block in floating register 2) and the process-running bit will remain TRUE. If any resume key is used to a running domain, that domain may lose its place on some queue.

• Overlapping Domains - The nodes of the invoking domain's domain should be distinct from the nodes of the invoked domain's domain. If this is not the case the invoking domain will acquire a trap code and the trap action will occur in place of the indicated invocation.

  Programming note: Domains will never overlap with the current design of space banks and domain creators, if current domain creators are the only holders of the domain tool.

Programming Note: Domains serve several functions typically provided by operating systems:

• Instantiation - For a program that serves many clients, the normal way in KeyKOS to distinguish among its clients is to have one domain per client. The domain's address space is divided into a portion that holds the program, which is shared among all such domains, and a portion that is not shared, and which holds client-specific data.

  Each of these domains can be described as different objects of the same type.

• Multi-programming or multi-tasking - Domains are independently scheduled.
• System Modularization (subroutines, information hiding, isolation) - Domains can enforce the concepts of data hiding and abstraction as used in modern system design.
• Locks - Stalling allows domains to be used to implement critical regions.

Design Note: Start keys and primary keys are purposely designed to be indistinguishable and interchangeable. The implementation of KeyKOS can be changed by moving functions into and out of the kernel without changing the logical environment of programs. Debugging environments can be built by substituting custom objects for standard ones.

Design Note: The trapping caused by rejected parameter words is inhibited for restart keys to prevent holders of restart keys from influencing (beyond impeding) the domain designated by the restart key.

NEXT