EROS Object Reference

Introduction

Research Edition, Release 0.2

D R A F T

[Return to Top]

The EROS system is made up of a number of objects that are interconnected to construct a complete, working system. This document provides a reference for all of the objects that are supplied with the EROS system. For each object, the manual provides a specification of the object's interface(s), a description of the behavior and use of each interface, and (where applicable) cross references to related objects and/or documents.

An object interface is exercised by invoking an appropriate key. The key names the service provider, a particular interface to that service, and the authority conveyed by the key.

For organizational purposes, this manual divides EROS objects into four categories:

Primary Objects	Primary objects are stateful objects that are directly implemented by the EROS kernel. Their content is saved to the disk by the checkpoint mechanism. Most objects and services, including programs, are constructed out of primary objects. Primary objects are rescindable; the space bank carries sufficient authority to invalidate existing primary object keys.
Kernel Objects	Kernel objects provide interfaces to the EROS kernel itself. These objects are stateless, and generally fall into one of two categories: Services that require direct access to the representation of a key, such as the discrim key. Services that interact with or control the single level store implementation, such as the checkpoint key. Kernel objects are not rescindable.
Device Objects	Device objects are the embodiment of machine-specific hardware devices. Unlike other EROS keys, not all device keys retain their validity across system restarts. Terminal keys, for example, are rescinded automatically as part of the restart process. Device keys are not individually rescindable.
Standard Processes	Standard processes are those objects included with the system that are not implemented by the EROS kernel, but are necessary or useful in the operation of the system. Standard processes include the process creator, the escrow agent agent, the space bank, processes implementing various policies for address space and process exceptions, and the like. Standard processes are constructed from primary objects, and can be rescinded by rescinding those objects.

Some keys are more sensitive than others. Keys whose misuse can compromise the security of the system in whole or in part are identified in this manual with the label TCB:

Range (TCB)

Such keys should not be held by processes that are outside of the Trusted Computing Base.

Other keys do not impact system security, but their availability is restricted for reasons of performance or administrative control. Such keys are said to be closely held, and are identified with the label Restricted:

Checkpoint(Restricted)

Certain keys are closely held, meaning that they are used only by system processes that are part of the trusted computing base. Generally, these keys provide access to kernel services that are not appropriate for general use. In the manual, such keys are identified by the letters TCB.

1. Invocation

Object interfaces are exercised by invoking the corresponding keys. There are several types of invocations, and every invocation follows a standard message structure.

1.1. Invocation Types

EROS provides three types of invocations: call, return, and fork:

Invocation

Description

call

The call invocation is used to invoke a service and wait for a reply. Every call receives at most one reply (there is no guarantee that the recipient replies at all). When a key is invoked by the call operation, the kernel fabricates a resume key that is unique to that call, and places the caller in the waiting state. The caller will resume when its resume key is invoked.

While a call operation is usually performed on a start key, this is not required. Calls on resume keys can be used to perform co-routine style invocations.

return

The return invocation is used to respond to a call. The returning process is placed in the available state, making it available for subsequent calls. When the process is next invoked, execution will pick up just after the return instruction.

An important fine point is that the returning process need not be returning to its most recent caller. It is sometimes useful to hold on to a resume key for later use and service some other caller first.

In addition, the return operation need not be performed on a resume key. A process can forward a message to a downstream process by returning to the downstream process and passing the content of the received message.

Because returning on a resume key is by far the most frequent case, and because the resume key type check is significant from a security perspective (invocations of resume keys never block) in most cases, the return invocation checks whether the invoked key is a resume key. It is possible to perform a return on other key types by using the npreturn invocation. The npreturn invocation is identical to the return invocation with the exception that it does not check the key type. An npreturn operation can therefore block indefinitely (for example, an npreturn on a start key to a non-available domain).

fork

The fork invocation is used to send a message to a recipient without waiting for a reply. Both the invoking and the receiving process are in the running state.

Unlike call and return operations, the fork operation does not return any information to the invoker. As a result, the "response" portions of the message structure are unused.

1.2. Invocation Content

Every invocation involves several pieces of information. On most architectures, everything but the data buffer is kept in machine registers. On more constrained architectures such as the Intel family, some of this information may be obtained indirectly from a message descriptor buffer. The mapping of the logical calling convention onto specific registers is architecture specific.

Send R0..R3	Send registers 0 through 3. Description Every invocation passes four registers from the caller to the recipient. It is the responsibility of the application to zero these registers prior to performing an invocation if their contents should not be transmitted. Usage Convention The first of these registers (SR0) is used to hold the order code or result code. The order code identifies the operation to be performed by the service that the capability names. The result code describes the outcome of the operation. In a call or fork invocation, this field is usually used to indicate the order code. In a return invocation, this field is used to describe the result code. Note that other combinations of call, return, and fork may find it convenient to make other uses of this field, as in the case of request forwarding.
Receive R0..R3	Receive registers 0 through 3. Description Every invocation passes four registers from the caller to the recipient. The recipient receives these four registers into the receive registers. On most architectures, the send and receive registers are identical; the transmitted registers are overwritten by the invocation's completion. It is the responsibility of the application to save and restore these registers around the invocation if their values should not be overwritten.
Send String	Up to 65536 bytes of data can be sent with each invocation. This portion of the message is optional. The sent data is not interpreted by the message transport.
Send Length	The length of the transmitted string.
Receive String	Up to 65536 bytes of data can be received with each invocation. If the invocation is a call, the received string will be the one passed during the invocation of the corresponding resume key. If the invocation is a return, the received string will be the one passed by the next start key invocation. If the invocation is a fork, no data will be received.
Receive Length	The length of the receive string buffer. This field is overwritten with the actual number of bytes received.
SK0...SK3	Every invocation transmits exactly 4 keys. The SK0 through SK3 fields name the key registers from which the keys should be transmitted. Not all messages require 4 key arguments; a void key can be passed in unused argument slots. In a call invocation, the K3 slot is overwritten by the kernel with a resume key to the invoking process.
RK0...RK3	Call and return invocations receive exactly 4 keys. RK0 through RK3 name the registers into which the keys should be received. Undesired arguments should be directed to key slot 0, which is defined to hold the void key at all times.
Key Info	The key info field is filled in by the kernel with each invocation. If the invoked key is a start key, the key info field will be populated with the value of the key info field of that start key. Use of distinct key info values allows a single process to implement multiple interfaces that convey different services or different access right. Since this field is populated by the kernel, the receiving process may assume that the key info field is unforgeable. If the invoked key is not a start key, the key info field will be zero.

1.3. Common Operations

Some operations are so universal that it is useful to have a convention for how these operations are requested. These conventions are not enforced by EROS, but it is a rare object that does not observe them. By convention, these operations are numbered relative to a standard value for the Alleged Key Type operation, KT. The standard KT value is the smallest number available under a two's complement interpretation of the machine's natural word size. On a 32-bit architecture, this value is -2,147,483,648, or 0x8000000.

Mnemonic

Request

Meaning

OC_KeyType

Return alleged key type The alleged key type returned depends on the key, and identifies the service that the key alleges to perform. The value is "alleged" because the result is returned by the object itself, which can therefore issue any answer it pleases. By convention, certain alleged key type values are reserved for the primary objects.

OC_Destroy

KT+1

Destroy This operation is used to ask an object to self destruct when one is done using it. An editor object, for example, can be sent the destroy request when the editing session is done.

The destroy order is simply a convenience. There are other mechanisms to ensure that objects that are broken or malicious can be forcibly destroyed.

1.4. Common Return Values

As with operations, certain operation results are common enough to warrant the assignment of conventional values:

Mnemonic	Value	Meaning
RC_OK	0	Operation completed successfully.
RC_Void	KT+1	Void key. Also returned when a rescinded key or a key to a malformed process is invoked.
RC_UnknownRequest	KT+2	Unknown request. Object does not support the given order code.
RC_RequestError	KT+3	Request error. Indicates that the arguments passed with the request were inappropriate or insufficient.
RC_NoAccess	KT+4	Access Violation. An attempt has been made to store into a read-only object.
RC_NoMoreNodes	KT+5	Space bank refused to provide more nodes.
RC_NoMorePages	KT+6	Space bank refused to provide more pages.
RC_NotPersistent	KT+7	A request was made on a kernel key that is not available in this implementation of the kernel because the kernel has been compiled without support for persistence. Generally this means that the application is running on an embedded version of the EROS system.

2. Documentation Conventions

Each object description begins with the object's name, and an optional TCB qualifier identifying closely held objects. This is followed by a description of the object's function:

Range (TCB)

A Range key conveys authority to a specific range of pages or nodes, and allows the holder to fabricate or rescind keys to objects within that range...

The overview description is followed by descriptions of the individual operations supported by the object:

GetObjectKey (oc=1)

The GetObjectKey operation creates a new object key for an object within the range named by this range key. The desired object is specified as an offset relative to the start of the range.

Request	data	[W] relative oid
Reply	RK0	new page key
Results	RC_OK	Operation completed successfully.
Results	1	Range error. Requested page offset is beyond the number of pages spanned by the page range key.

This example describes a service that accepts a one-word argument as data and returns a key in slot 0 of the returned message. The operation has two possible outcomes: success or range error.

Several parts of both the request and the reply message are ommitted from the description. Keys 0 through 3 of the request message are unused by this operation. The return values in Keys 1 through 3 are undefined, and no data is returned.

In general, it is good practice to specify void keys for unused key arguments. This ensures that the recipient does not gain access to authorities that it shouldn't. In addition, existing orders may be extended in the future to interpret these slots, and planning ahead by sending void keys in unused slots will prevent incompatibility. The interface glue layer provided for C and C++ does this automatically.

2.1. Data Field Interpretation

While the data portion of the message is not interpreted by the message transport, the reference manual specifies the expected argument types for each invocation. The type of each argument is indicated by a preceding letter within square braces, which may be one of the following:

Letter	Meaning
B	A single byte value
H	A two byte value (halfword)
W	A four byte value (word)
I	A signed, four byte value (integer)
L	An eight byte value (longword)
N	A 96 bit value (a bignum), used to describe an address space offset.
S	A string of ascii characters
U	A string of UNICODE characters

Where an argument consists of a fixed length sequence of items of like type, the type specifier may include an optional colon followed by a count, as in [W:4]. Where an argument consists of a variable length sequence of items of like type, the type specifier is followed by an asterisk, as in [S*].