Description

A Node provides persistent storage for a fixed number of keys. Just as the page is the basic unit of storage for user data, the Node provides the basic unit of storage for 32 keys. Every Node corresponds to one or more unique locations on some persistent storage medium, such as a disk drive. In most installations, Nodes are therefore available in large supply. Applications acquire Node keys by requesting them from a Space Bank. Nodes are primarily used to construct address space trees. The term ``node'' refers to their use as tree nodes in address spaces.

Node keys may carry several attributes that restrict the behavior of operations on the node in certain contexts. A given node key may carry some, all, or none of the following restrictions:

Read-Only	Prohibits modification of the node. New keys cannot be written to this node's slots. When the node appears in a memory tree, all stores to pages below this node in the tree will generate access violations. A read-only node key may not be used to perform the swap, compare, zero, or write number operations.
No Call	Prohibits the invocation of a keeper via this node. When the node appears in a memory tree, keepers specified at or below this node are ignored. If an access violation or invalid reference occurs within the subspace rooted at this node, the nearest keeper above the node (if any) in the memory tree will be notified of the fault. For a red address space node key (see address space), this attribute causes the forwarding of invocations to the space keeper to be suppressed.
Weak	A weak node key performs the sensory transformation (see sensory keys in the concepts section) on any key that is loaded via this node. Keys returned by the copy and swap operations will be desensitized so as not to (transitively) convey mutate authority on any object. When a weak node key appears in a memory tree, key load operations from locations within that subspace will return similarly desensitized keys.

Nodes may act in several roles at once; It is acceptable, and occasionally useful, to hold both a Node key and a address space key to the same Node of storage. This is analogous to having both const and unrestricted pointers in programming languages. The correctness of the EROS security architecture is not compromised by doing so. Similarly, multiple node keys with distinct attributes can designate the same node.

One consequence of this is that Nodes suffer from an overabundance of key types.

---

Operations

Check Alleged Key Type (OC = KT)

Returns the alleged type of the key.

Reply	R1	AKT_Node: Key is some type of node key.
Reply	R1	Value of the key info field, as described above.

Copy Key (OC = 0)

Copies the key in slot N (0 <= N <= 31) of the Node to the key register named in key slot 0 (RK0).

Request	R1	The node slot N to be copied.
Reply	RK0	A copy of the key in the requested slot.
Result	RC_OK	Operation completed successfully.
	RC_RequestError	Slot number was invalid.

Swap Key (OC = 1)

Places the passed key (SK0) in slot N (0 <= N <= 31), returning the old key in the designated return register (RK0).

Request	R1	The key slot N to be exchanged.
	SK0	The key to be written to the indicated Node slot.
Reply	RK0	The previous value of the key in slot N.
Result	RC_OK	Operation completed successfully.
	RC_NoAccess	Access violation.
	RC_RequestError	Slot number was invalid.
	RC_Process_Returnee	Operation would modify the returnee. This usually means that the node key names a node that shares structure with the process named by the resume key for this operation.

This operation is not permitted for sensory or fetch keys.

Make Node Key (OC = 64)

Make Address Space Key (OC = 65)

Returns a node, or address space key to the invoked key, using the passed data value as the key info field. The requested attributes of the new key are or'd with the attributes of the invoked key; the make node key operation can never reduce the restrictions on a node key.

See also the Address Space page.

Request	R1	The desired key info field for the newly created key, using the encoding shown above. Must be <= 65535.
Reply	RK0	A copy of the invoked key, whose BLSS value is as specified in R1 and whose attributes are the logical OR of the requested attributes and the attributes of the invoked key.
Result	RC_OK	Operation completed successfully.
	RC_RequestError	Request format error. These requests require a word data argument whose value is <= 65535.
	RC_NoAccess	Access violation. Sense keys may only be used to construct sense keys. Fetch keys can only be used to construct fetch keys or sense keys.

Compare Key (OC = 72)

Tells whether the passed key key names this Node.

Request	SK0	The key to be validated.
Reply	R1	0: SK0 is some other key.
		1: SK0 is a Node, fetch, sense, or address space key for this Node.
Result	RC_OK	Operation completed successfully.
	RC_NoAccess	Access violation.

This operation is not permitted for sensory or fetch keys.

Clear Node (OC = 73)

Replaces all keys in the Node with the void key.

Result	RC_OK	Operation completed successfully.
	RC_NoAccess	Access violation.
	RC_Process_Returnee	Operation would modify the returnee. This usually means that the process key names the same process that is named by the resume key for this operation.

This operation is not permitted for sensory or fetch keys.

Key Data (OC = 74)

Returns the key data field of the invoked Node key. For an explanation of the key data field and its use, see the address space description.

Reply	db	The value of the key's data byte
Result	RC_OK	Operation completed successfully.

Clone Node (OC = 80)

Copies all of the keys in the passed in Node into the Called node, making it a clone. The old keys in the invoked node are lost.

The Clone Node operation is not permitted on a read-only node key.

Request	SK0	The Node Key clone from.
Result	0	Success. The node now holds the same keys as SK0.
	RC_RequestError	SK0 is not a Node key.
	RC_NoAccess	The invoked node key is read-only. The node remains unchanged.

Write Number (OC = 96)

Fabricates a number key in slot N (0 <= N <= 31) whose values are obtained from the sent registers.

Request	R1	The slot number to overwrite.
	W	The least significant 32 bits of the value.
	W	The middle 32 bits of the value.
	W	The most significant 32 bits of the value.
Result	RC_OK	Operation completed successfully.