Figure 2-7Meters measure and control the quantity of resources that domains use. Meters may be used to prevent domains from proceeding. Cutting off a meter does not destroy data. The meter may be turned back on in such a way that affected domains restart from where they left off. Meters are organized into trees with the primordial meter at the root, domains at the leaves, and meters at the nodes of the tree.
A meter key is a specific type of key that designates a node. A meter is a node viewed through a meter key.
A node key may be used to obtain a meter key, which permits the node to be used as a meter. A meter key only allows the holder to use the node as a meter, or to create subsidiary meters.
Slot 1 of a meter node designates another meter node by a meter key. The first meter is said to depend on the second meter. If meter A depends on meter B, A is said to be inferior to B and to all meters to which B is inferior. Any resource measured by a meter is measured by the meter that it depends on (and by all meters to which it is inferior).
A domain which depends on a meter node causes the counters in that node to count the use of resources by the domain.
The primordial meter key is a valid level 0 meter key. B is a valid meter of level n+1 if:
In other words, a valid meter key must (among other things) point to the head of a chain of nodes, via slot 1 of those nodes, that leads to the primordial meter key. This chain may involve only meter keys and may have at most 20 keys.
The counters in a meter node (each of which is a data key) are decremented as the resources are used.
Programming note: When constructing meters, the data keys in slots 4 and 5 should be initialized with data keys that are all ones. This action will provide for compatibility with future versions of KeyKOS by preventing meter traps for these resources.
When the CPU time counter in a meter node is zero and a domain tries to decrement it, the counter remains zero and the key in slot 2 of that meter node is implicitly invoked. The key must be a gate key or the Error Key as described in the section in this chapter entitled, "How a Domain Invokes a Key".
Figure 2-7
Programming note: There is a programming convention for slot 14. When the CPU counter is zeroed to stop domains that depend on the meter, the old value of the counter is saved in Slot 14. This convention allows a single meter to be used for both measuring elapsed CPU time and for stopping the domains that depend on the meter.
Programming note: Whenever a domain's meter is invalid (malformed) the kernel causes the domain to trap to its domain keeper.
A charge set is used to determine how many pages are referenced by domains running under one or more meters. Charge sets may be either active or inactive. Inactive charge sets have no pages in them. Active charge sets have zero or more pages and a 64-bit TOD value that is set whenever the charge set is activated.
When a domain, running under a meter that holds a a charge set key, references a page that is not already in the set, that page is added to the set. If the set was inactive it is activated and its TOD value is set to the current TOD value.
Implementations may arbitrarily inactivate a charge set when its space is needed or for other reasons.
A segment is an array of bytes. A segment key designates a segment. This section describes how segments may be defined by using pages, nodes, and keys. Segments provide long term storage for data. They may be used to organize larger objects from pages in the KeyKOS single level storage.
A memory key defines a segment and provides access to the bytes of that segment. The use of a memory key to access the bytes of a segment is called a memory reference. A memory key may permit read, but not write, access to a segment.
A domain's addressing segment is used to define the interpretation of addresses generated while the domain executes instructions. It is defined by the key in C3.
A Memory Key is DK(0), a page key, or a segmode key.
DK(0) is a null memory key. It causes an error if used in addressing memory.
A Page Key defines 4096 bytes of data.
A segmode key is a segment key, node key, or sense key or, if the right four bits of the data byte are not 0, a fetch key. These keys designate nodes and at the same time indicate some information about the format of the node. The node is interpreted as a segment node when viewed through a segmode key.
The eight bits of the data byte of a segmode key are interpreted as follows:
Figure 2-8
RO is the read-only bit. When it is one, all stores via this key are prevented from occurring.
NC is the no-call bit. When it is one, no segment keeper defined in any segment node reached via this key will be invoked.
The LSS (log16 of slot size) field defines the segment as being one of two formats. If the LSS is zero then the segmode key is red. If the LSS is greater than or equal to 3 and less than or equal to 12 then the segmode key is black. Any other value of LSS will generate an error when the key is used to address memory.
Each segmode key has an associated slot size code (SSC) which specifies the addressing range defined by each slot of the segment node it designates. The SSC for a black segmode key is equal to the value of the LSS in the key. The SSC for a red segmode key is found in the data key in slot 15 of the node it designates.
Programming note: A segment node may have more than one SSC if there is more than one segmode key to the node. A single node may be treated as red when seen through one key and black when seen through another.
A node designated by a red segmode key must contain a data key in slot 15 called the format key. The right 32 bits of its value are formatted as follows (each field depicts four bits):
Figure 2-9
If PP2 is zero, an explicit invocation of a segment key to this node will produce a node key to this node as parameter 2 for the invoking domain. If PP2 is one, parameter 2 will be as provided by the invoking domain. All other values of PP2 cause the segment node to be malformed.
The four-bit fields F must be 15. (If not, the segment node is malformed.)
BGK is the slot number in this node of the background key; with 15 indicating that there is no background key.
KEEP is the slot number in this node of the segment keeper key with 15 indicating that there is no segment keeper key defined in this node.
Slots 0 through INIT-1 of this node are the initial slots. Note that there can be at most 15 initial slots in a node designated by a red segmode key.
SSC is the slot size code. If SSC is less than 3 or greater than 12 then access will generate error code 9.
Programming note: The segment key holder may communicate with the segment keeper. If the segment key's no-call bit is zero and it is invoked explicitly, the result is an invocation of the segment keeper key.
Programming note: A background key may be referenced by background window keys in this node and reached through segmode keys in this node. This mechanism allows one or more windows to be set up and the segment they reference to be changed by changing only the background key.
In a node designated by a black segmode key, all 16 slots are initial slots. The SSC is defined in the LSS of the segmode key.
The initial slots of a segment node define consecutive ranges of addresses of size 16^ssc called the addressing range of the slot. The addresses, relative to the address of the segment node, for the first initial slot are 0 to 16^ssc-1, the second is 16^ssc to 2(16^ssc)-1, etc.
Initial slots must contain memory keys or window keys. All other keys cause error codes when addresses are applied to them.
Figure 2-10
In the local window key, kkkk is the slot number in the same node that holds the memory key to the windowed data. The background window key uses the current background key for the windowed data.
The portion of the effective address that located the window key slot is discarded and the remainder is added to ... aaaa0000 00000000 (... aaaa is the page offset). ... aaaa0000 00000000 must be a multiple of 16^ssc. This sum is used to address the windowed data.
If W is 1 (read-only) then addresses defined by this key cannot be used to store. If C is 1 (no-call) then no segment keeper defined in any segment node reached via this key will be invoked.
A domain can generate addresses in the range 0 to 2^31-1 (IBM System 370s generate addresses less then 2^24 in 370 mode, in XA mode they generate addresses that are less than 2^31). The data referenced by these addresses are located by applying the address to the domain's addressing segment key.
The result of this application is:
The following defines the result of applying an address to a key:
If the key is a data key the result is error code 5.
If the key is neither a page key nor a segmode key, the result is error code 2.
If the key is a page key and the address is greater than 4095, the result is error code 3. If the page key is read-only and the reference is a write reference, the result is error code 1. Otherwise, the result is to access the location at that address in the page.
If the key is a segmode key it is validated. If its LSS = 0 and the designated node's format key is not a data key, the result is error code 7. If the value of SSC is not in the range 3 <= SSC <= 12, the result is error code 9. If there is some other error in the format key the result is error code 8. If the format key defines a background key, the background key is in effect for this node and for all subsequent nodes until a new background key is defined.
If the read-only bit in the data byte of the segmode key is on and the reference is a write reference, the result is error code 1. Otherwise, the segmode key is considered valid. If more than one error code applies, it is implementation dependent which is generated.
If the segmode key is valid then:
In the process of applying an address to the domain's addressing segment, a (perhaps empty) sequence of segment nodes, called the access path, was examined.
If the result of applying an address to the domain's addressing segment is an error, the unit of operation is nullified. (However, there is an exception in the case of the TR, ED, and EDMK instructions (see "Recognition of Access Exceptions" in IBM System/370 Principles of Operation.)) The kernel then determines if there is a segment keeper key to implicitly invoke: Consider the sequence of nodes forming the access path. From this sequence eliminate all nodes after passing any key with the no-call bit on. Then eliminate all nodes that do not hold a segment keeper key. If any nodes are left, the last one is called the last kept node. The segment keeper key implicitly invoked is that of the last kept node.
If there is a segment keeper key to implicitly invoke, the domain makes an implicit invocation of it. This invocation is called a segment fault. The parameter word passed is the negative of the error code. The argument string is six bytes long and consists of the address (with the right 12 bits set to 0) that was applied to the last kept node.
If there is no segment keeper key to implicitly invoke, a trap code with TC0=4 is placed in the domain.
Figure 2-11
The access path is divided into three parts: from the beginning through the first key with SSC < 6; from there through the first key with SSC < 4; and the rest. The number of nodes in each part may not be more than 20; otherwise, the result is an error with code 6.
Within one unit of operation (see IBM System/370 Principles of Operation), several memory accesses may occur (at most, eight pages will be involved), each of which involves an access path. For each unit of operation there is also a node path from the domain root to the primordial meter key.
Consider three sets of nodes: the nodes in all access paths, the nodes in the meter path, and the three nodes of the domain. At most, a node may belong to one of these sets. Implementations may limit the total number of nodes in these three sets to 100. If these conditions are not met, the domain may fail to make headway.
Implementations may impose the limit that if, during one unit of operation, one page is addressed with a virtual address that allows writing and another address that does not, the unit of operation will not finish. CPU resources will continue to be consumed.
Programming note: Every access to memory is via the addressing segment. This means that changes to the addressing segment take effect immediately.
Programming note: The memory key (a page key or a segmode key) provides the opportunity to cause some data to appear in one's virtual storage. Placing the memory key in an addressing segment slot causes the data to appear at that address. Also, there may be a segment keeper associated with the key that the holder may be more or less aware of. Besides fetching and storing from addresses defined by the memory key, the holder can call the segment keeper concerning anything of mutual interest. There is no general assurance that data provided by the memory key will not change without the key holder changing it. However, if the no-call bit is turned on in the memory key, the key holder can be sure that no segment keeper is observing the pattern of accesses.
Programming note: Being a Segment Keeper. Normally the segment keeper key is a start key. The object it designates (the segment keeper), has control over what data is described by the segment key. Because it is given a node key to the segment node, the segment keeper may delete or change data described by the segment. It can also create data, page by page, when the segment user comes to use the data. (This can be done in such a way as to provide the illusion that the data was always there.)
Design note: The read-only and no-call bits in segment keys are to prevent information from passing from the key holder to the segment and its keeper. Such a segment key can be given to a domain without fear of it being used to export information. This technique can not be used if the segment keeper is a necessary part of the function of the segment.
Programming note: A red segment key with a format key that specifies PP2 as one can be used for a synthetic node key. The segment keeper performs the node simulation. The key can also be used directly as a memory key.
Programming note: Building an expandable 50-page segment. First build three 16-page black segments and one two-page black segment. The segment nodes defining the 16-page segments must be black in order to hold the 16 page keys for the constituent pages. Then place node keys with LSS = 3 to these segments in a node that is formatted as a red segment node. Place the start key to the segment keeper which will expand the segment in the red segment node.
Figure 2-12
If the top node were black, segment keys to the node would specify an SSC of 4 and the segment would be forever limited to 256 pages because there is no general way to find and change all of those segment keys. With a red segment node, the SSC can be increased to meet future requirements because the only record of the SSC is in the format key.
Programming note: The holder of a segment key may call the segment keeper with a parameter word of -1. The segment keeper has no way of distinguishing this case from the implicit invocation due to a reference.
Programming note: Background keys ease the process of making a virtual copy of a segment for which there is only a segment key available. However they cost an additional level of segment node for each new virtual copy. The virtual copy segment keeper does not have this problem. See KeyKOS Object Reference (KL230).