PREVIOUS

Chapter 3. Primary Functions

While some services are obtained via gates, others are obtained directly from the kernel itself. Keys that are not gates are called primary keys.

A primary key appears to the holder as a start key. Invoking a primary key causes the kernel to perform the primary function and return to the key provided as the last key parameter in the invocation. Primary keys are purposely designed so it is difficult to distinguish them from start keys; indeed some implementations may replace some of them with start keys that provide the same function.

If the invocation is a call, a return key to the invoker is implicitly provided as the last parameter. For other kinds of invocations, a resume key must be explicitly passed, or there will be no return. (It is as if the returner key were used to perform the return.)

The return is immediate unless otherwise specified; if the return is delayed the effect is as though the kernel held the return key.

Unless otherwise specified, if a primary key is offered a byte string shorter than that required, the string is padded on the right with zero bytes. If it is longer and the additional bytes are zero, the function is the same as specified in this section. (Additional non-zero bytes are reserved.)

If a primary key is offered keys in positions not specified on the description of the particular order code, they are ignored. It is as if the primary key specified an entry block that did not accept these keys.

Primary keys return kt+2 for invalid order codes.

Certain primary functions are performed by miscellaneous keys. These keys do not designate a page or node but refer to some object internal to the kernel. e.g. The wait key and wait objects, range keys and range objects, and device keys and device objects. These objects are designed so they have no state or so that their state may be reset upon a kernel restart.

Restricted Primary Keys

Certain miscellaneous keys are designed to be limited to special programs. Since, in a capability system like KeyKOS, all programs run with restricted access, this restriction is one of degree rather than the supervisor state vs. problem state type of restriction provided by the System/370. Each restricted key description has a note as to why it is restricted.

I/O Keys

Primary keys that do not always return immediately, e.g. device I/O , can be distinguished from start keys.

Invoking such a key may cause some or all of the side effects of the key to occur even though the invocation appears not to have occurred. In effect, when the key senses that an invocation is about to occur, it performs its side effects (which may include waiting for some event) and enters a special state. An invocation of the key can only proceed from the special state; when it does, the return (of parameters saved when the side effects were performed) occurs immediately.

Only one domain should be trying to invoke an I/O key at any one time and it should not change its mind about what it is doing. This is one reason that such keys are restricted.

Introduction to Primary Keys

Primary keys are introduced briefly below (alphabetically). A full description can be found in the KeyKOS Object Reference (KL230).

BDEVICE

Device Key ManagerBDEVICE allocates and deallocates device I/O keys.

BWAIT

A small fixed number of BWAIT keys are implemented to allow domains to delay execution until a specific amount of time has passed.

CDAPEEK

A CDAPEEK key allows the holder to look at the backup version of any page or node The backup version of a page or node is the version that would exist if the system restarted from the last checkpoint.

Charge Set

A Charge Set key gives the holder access to KeyKOS's memory of which data a domain has accessed recently. The charge set depicts a set of pages and nodes and is used to measure the utilization of main storage and channels by a domain.

Charge Set Tool

This key allows the generation of charge set keys.

Checkpoint

The Checkpoint key is used either to wait for or to take a complete system-wide KeyKOS checkpoint.

Data

A data key returns a non-negative integer value. Data keys always return a specific non-zero return code (x'80000001') so that domains are more likely to sense when a key they hold designates a deleted object.

Device I/O

Device I/O keys are created by BDEVICE and give the holder authority to issue restricted channel programs for the device. The following restrictions are enforced:

Data chaining, PCI, and indirect data address words may not be used.

Pages referenced must exist, even if SKIP is specified.

All but the last channel-control-word must specify command chaining; the last must not.

Discrim

Discrim provides a method for obtaining basic information about keys. This information can be gathered with much more difficulty using self-destructive or statistical techniques.

Domain

A domain key grants its holder the ability to extract and insert all data and keys that would be available to a program running in the domain. It also provides access to portions of the domain that are not automatically available to programs running in the domain.

Domain Tool

A domain tool key allows the holder to identify keys associated with domains.

Error

The error key is for emergency use by domains "close" to the KeyKOS kernel. It is invoked when there is an error condition that cannot be handled by any program outside the kernel.

External Migrator Tool

This key is an I/O key used to optimize migration operations. It is designed for use by only one domain.

Fetch

A fetch key is a key to a node mainly used for fetching copies of keys in the node.

I/O Measure

The I/O Measure key provides several measurements of I/O performance.

IPL

IPL is an I/O key used to restart the KeyKOS kernel.

Journalize Page

The journalize page key is invoked to preserve the current data in a page across checkpoint restart. That is, the checkpoint image of the page is updated to the current contents of the page.

Kerrorwait

This key returns messages about hardware errors detected by the KeyKOS kernel.

Keybits

Keybits returns a bit pattern for a key whose contents may change in new releases of KeyKOS and whose interpretation is proprietary. The bit pattern returned for a particular key is guaranteed to be the same for a particular version of KeyKOS.

Meter

A meter key is a key to a node through which the node is viewed as a meter.

Node

A node key gives the holder the authority to read and write keys in the node. A node key is also used to create attenuated keys to the node, such as a fetch key and a meter key.

Page

A page key allows the storing of data into the page designated by the key and allows the creation of a read-only key to the page.

Peek

A peek key allows read-only access to all of main memory. It is also used to enable the PER hardware.

Range

Range keys are the primary tools of space banks. Each range key controls a definite set of pages or nodes. A key that controls a set of pages is called a page range key and a key that controls a set of nodes is called a node range key.

Returner

Returner returns information passed to it. A domain is guaranteed never to stall invoking Returner, which makes Returner a useful tool for domains that provide public services and must return to their invokers without the possibility of stalling on that return.

Segment

A segment key allows a construction of nodes and pages to be viewed as a segment.

Sense

A sense key returns sensory versions of keys. A sensory version of a key is a key through which information can only flow toward the holder of the key.

NEXT