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
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
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
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.
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
- Device Key ManagerBDEVICE allocates and deallocates device I/O keys.
- A small fixed number of BWAIT keys are implemented to allow domains
to delay execution until a specific amount of time has passed.
- 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
- Charge Set Tool
- This key allows the generation of charge set keys.
- The Checkpoint key is used either to wait for or to take a complete
system-wide KeyKOS checkpoint.
- 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
Data chaining, PCI, and indirect data address words may not be
Pages referenced must exist, even if SKIP is
All but the last channel-control-word must specify command
chaining; the last must not.
- 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.
- 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
- 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.
- 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 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.
- This key returns messages about hardware errors detected by the
- 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.
- A meter key is a key to a node through which the node is viewed as a
- 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.
- 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.
- A peek key allows read-only access to all of main memory. It is also
used to enable the PER hardware.
- 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 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.
- A segment key allows a construction of nodes and pages to be viewed
as a segment.
- 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.