Invoking is the basic operation on keys. Invoking a key is also called jumping at the key and an invocation is called a jump.

Parameters

Data Parameters
Two data parameters may be passed: the 32-bit (_order code) and the (_byte string). The byte string is a sequence of from 0 to 4096 8-bit values. The data is copied {"call by value"}.
Data in the order code is handled more efficiently by the kernel than data in the byte string.

Key Parameters
The jumper offers four keys to be passed, numbered 0 through 3. The keys are copied {"call by value"}.

A key invocation is either explicit or implicit.

Explicit Invocation

A domain invokes a key explicitly by issuing one of three SVC instructions with bits -33 and -32 of its C4 both one.

(_call) {SVC 253}

In a call invocation, the invoking domain enters the waiting state, that is it ceases to have a process. The last key parameter passed is always a {newly created} return key to the invoking domain.
In anticipation of that resume key being invoked {by someone else}, the domain normally loads an entry block before executing the call. See (p1,jespec).

(_return) {SVC 254}
In a return invocation, the invoking domain loses its process and enters the available state.
In anticipation of some start key to this domain being invoked {by someone else}, the domain almost always loads an entry block before executing the return. See (p1,gates).

(_fork) {SVC 255}
In a fork invocation, the invoking domain remains running.

Implicit Invocation
There are several events in a domain that cause an implicit invocation to be made. In an implicit invocation, the invoking domain enters the waiting state and a resume key is passed as the last key parameter as in a call. See (p1,d2) about domain keepers, (p1,metgate) about meter keepers and (p1,segkeepslot) about segment keepers.

Step 1. The key to be invoked is identified and the data and key parameters are {conceptually} copied. 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 action of invoking the key takes place. This action varies according to the specific key invoked. If the key to be invoked is a gate key, see (p1,gates). If the key to be invoked is not a gate key, see (p2,primary).

With few exceptions, step 1 is {conceptually} completed before step 2 is begun. Step 1 is the same regardless of what key is to be 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 invoked key and not in the other direction.

The exceptions are:

Stalling
Stalling means that the execution of the invoking domain is suspended just before step 1. When the reason for stalling ceases, execution proceeds. While a process is stalled at an explicit jump, it is still in the running state with its PSW indicating the Supervisor Call {SVC} instruction. A stalled domain consumes very few resources {despite the fact that there is a process in it}.

If the invoked key is a start key, see (p1,entrystall).

{arcane}The invoking domain will stall until all pages and nodes needed to complete the jump are in core. This statement is at the kernel level of description. For example, in the case of keys other than gates, the last key parameter, which must be a resume key, refers to a domain and that domain must be in core to complete the jump. This situation will be brief unless a page or node is dismounted. See also (p2,returner-note).

Upon jumping to a primary key, all pages required to hold the parameter of the returnee are faulted into memory. In a gate jump, only those parameter pages required to hold the actual argument are faulted into memory.

To this extent, gate jumps and primary jumps are different. This might interfere with synthesizing primary keys: the user might sense the difference with charge sets. However, the difference is easily detectable by anyone with access to the real-time clock, so this difference does not represent a serious security exposure.

{arcane}{ni}A fork invocation of a gate key may stall when creating the new process would exceed a process limit built into the kernel. In this case the kernel calls the decongester {(kernel-logic,decngst)} to help. The domain issuing the fork need not be aware of this.

{ni}Some versions of Gnosis may provide buffering to avoid stalling. In this case the invoked key and the parameters would be held in a (_jump packet) and the disposition of the invoking domain would occur immediately. For example, a domain executing a fork to a start key to a busy domain could find that the fork completes, that is, the domain goes on to the instruction after the fork, while the action of invoking the start key has not yet occurred. You should not write programs that depend on the effects of stalling.

{arcane}Certain I/O keys {see (p2,iokeys)}.

Gate keys that accept strings in two pages {see (p1,stringcopy)}.

All of the action of invoking the key {at the kernel level of description} depends on the meter of the invoking domain.

Exit Block Format
The invoking domain provides an (_exit block) in general registers 0 and 1. The format is described below. Bits 6 and 7 of the exit block are reserved and must be zero.

MMMM AA00 GGGG 0000 KKKK KKKK KKKK KKKK (8*)CCCC

"MMMM" Key argument presence bits - (keyargs) "GGGG" Gate key - (gatekey) "AA" String argument control - (argpage) "KKKK" Key argument slot numbers (keyargs) "CCCC" Order code - (ordercode)

The Key to Invoke
Bits 8 through 11 of the exit block specify which of the 16 general key registers of the domain contains the key to be invoked.

Data Arguments
Order Code
The invoking domain provides the 32-bit order code from general register 1.

Argument Page and String
If bits 4 & 5 of the exit block are 01, general registers 2 & 3 hold the address and length of the byte string. The length, in register 3, is considered as a 32-bit unsigned integer.
The length must not be more than 4096. {This limit may be increased sometime.} If it is more, the trap code is set with TC0 = 5 and subcode 6.

If bits 4 & 5 of the exit block are 11, general registers 2 & 3 hold the address and length of the byte string argument within the registers. Address 0 is the left byte of R0, address 63 is the right byte of register R15, address 64 is the left byte of register F0 and address 95 is the right byte of F6.

If bits 4 & 5 of the exit block are 00 a zero length string is provided.

If bits 4 & 5 of the exit block are 10 the domain gets trap code '050000000002'. {This combination once specified that the string was held in a page designated by a key.}

Key Arguments
For I from 0 through 3, key number I is, if bit I of the exit block contains a one, the key in the invoking domain's general key register specified by the four bits beginning with bit 16+(4*I) of the exit block. If bit I of the exit block contains a zero, key number I is a zero data key. If the domain specifies a call invocation, an exit key is produced which becomes key number 3, and bit 3 and bits 28 through 31 of the exit block are ignored. The invocation may be faster, however, if these bits are zero.

See (p3,ejp) about passing more data or keys than allowed here.

We give here some notation that will be used in this report to describe particular key invocations. {See (p3,langintf) for calls from some programming languages.}

To depict the code that calls key G we will write: "G(...;...==>...;...)". In this notation the text between "(" and "==>" denotes the values {arguments} passed to G. Since the invocation is a call, a return key to the invoking domain is passed {but not shown}. Assuming that that the return key is later invoked, the text between "==>" and "(" denotes the values passed {i.e., returned to the original domain}. In both cases, the text before the ";" represents the data, and the text following represents the keys.

In representing the data values passed and returned, the field may be: "" {empty}, "oc" or "oc, bs". Here "oc" means order code and "bs" means byte string. The notation "((2,u), (6,b))", for example, denotes an 8-byte string consisting of a 2 byte field of value u followed by a 6-byte field of value b. If the order code is omitted it is assumed to be zero.

In the key parameters and results, 0 to 4 key slots may be mentioned, separated by commas.

Thus "direc(3,'puzle.for';==>c;K)" might depict a call to a directory entry "direc" offering order code 3 and name "puzle.for", expecting in return an error code c and a key K.