The ROM session interface makes a piece of data in the form of a dataspace available to the client.

Session creation

At session-creation time, the client specifies the name of a ROM module as session argument. One server may hand out different ROM modules depending on the name specified. Once a ROM session has been created, the client can request the capability of the dataspace that contains the ROM module. Using this capability and the region map of the client's PD session, the client can attach the ROM module to its local address space and thereby access the information. The client is expected to merely read the data, hence the name of the interface.

ROM module updates

In contrast to the intuitive assumption that read-only data is immutable, ROM modules may mutate during the lifetime of the session. The server may update the content of the ROM module with new versions. However, the server does not do so without the consent of the client. The protocol between client and server consists of the following steps.

1. The client registers a signal handler at the server to indicate that it is interested in receiving updates of the ROM module.

2. If the server has a new version of the ROM module, it does not immediately change the dataspace shared with the client. Instead, it maintains the new version separately and informs the client by submitting a signal to the client's signal handler.

3. The client continues working with the original version of the dataspace. Once it receives the signal from the server, it may decide to update the dataspace by calling the update function at the server.

4. The server responds to the update request. If the new version fits into the existing dataspace, the server copies the content of the new version into the existing dataspace and returns this condition with the reply of the update call. Thereby, the ROM session interface employs synchronous bulk transfers as described in Section Synchronous bulk transfer.

5. The client evaluates the result of the update call. If the new version did fit into the existing dataspace, the update is complete at this point. However, if the new version is larger than the existing dataspace, the client requests a new dataspace from the server.

6. Upon reception of the dataspace request, the server destroys the original dataspace (thereby making it invisible to the client), and returns the new version of the ROM module as a freshly allocated dataspace.

7. The client attaches the new dataspace capability to its local address space to access the new version.

The protocol is designed in such a way that neither the client nor the server need to support updates. A server with no support for updating ROM modules such as core's ROM service simply ignores the registration of a signal handler by a client. A client that is not able to cope with ROM-module updates never requests the dataspace twice.

However, if both client and server support the update protocol, the ROM session interface provides a means to propagate large state changes from the server to the client in a transactional way. In the common case where the new version of a ROM module fits into the same dataspace as the old version, the update does not require any memory mappings to be changed.

Use cases

The ROM session interface is used wherever data shall be accessed in a memory mapped fashion.

• Boot time data comes in the form of the ROM sessions provided by core's ROM service. On some kernels, core exports kernel-specific information such as the kernel version in the form of special ROM modules.

• If an executable binary is provided as a ROM module, the binary's text segment can be attached directly to the address space of a new process (Section Component creation). So multiple instances of the same component effectively share the same text segment. The same holds true for shared libraries. For this reason, executable binaries and shared libraries are requested in the form of ROM sessions.

• Components obtain their configuration by requesting a ROM session for the "config" ROM module at their respective parent (Section Component configuration). This way, configuration information can be propagated using a simple interface with no need for a file system. Furthermore, the update mechanism allows the parent to dynamically change the configuration of a component during its lifetime.

• As described in Section Publishing and subscribing, multi-component applications may obtain data models in the form of ROM sessions. In such scenarios, the ROM session's update mechanism is used to propagate model updates in a transactional way.

The report session interface allows a client to report its internal state to the outside using synchronous bulk transfers (Section Synchronous bulk transfer).

Session creation

At session-creation time, the client specifies a label and a buffer size. The label aids the routing of the session request but may also be used to select a policy at the report server. The buffer size determines the size of the dataspace shared between the report server and its client.

Use cases

• Components may use report sessions to export their internal state for monitoring purposes or for propagating exceptional events.

• Device drivers may report information about detected devices or other resources. For example, a bus driver may report a list of devices attached on the bus, or a wireless driver may report the list of available networks.

• In multi-component applications, components that provide data models to other components may use the report-session interface to propagate model updates.

The terminal session interface provides a bi-directional communication channel between client and server using synchronous bulk transfers (Section Synchronous bulk transfer). It is primarily meant to be used for textual interfaces but may also be used to transfer other serial streams of data.

The interface uses the two RPC functions read and write to arbitrate the access to a shared-memory communication buffer between client and server as described in Section Synchronous bulk transfer. The read function never blocks. When called, it copies new input into the communication buffer and returns the number of new characters. If there is no new input, it returns 0. To avoid the need to poll for new input at the client side, the client can register a signal handler that gets notified upon the arrival of new input. The write function takes the number of to-be-written characters as argument. The server responds to this function by processing the specified amount of characters from the communication buffer.

Besides the actual read and write operations, the terminal supports the querying of the number of new available input events (without reading it) and the terminal size in rows and columns.

Session creation

At session-creation time, the terminal session may not be ready to use. For example, a TCP terminal session needs an established TCP connection first. In such a situation, the use of the terminal session by a particular client must be deferred until the session becomes ready. Delaying the session creation at the server side is not an option because this would render the server's entry point unavailable for all other clients until the TCP connection is ready. Instead, the client blocks until the server delivers a connected signal. This signal is emitted when the session becomes ready to use. The client waits for this signal right after creating the session.

Use cases

• Device drivers that provide streams of characters in either direction.

• A graphical terminal.

• Transfer of streams of data over TCP (using the TCP terminal).

• Writing streams of data to a file (using a file terminal).

• User input and output of traditional command-line based software.

• Multiplexing of multiple textual user interfaces (using the terminal-mux component).

• Headless operation and management of subsystems (using the CLI monitor).

UART

The UART session interface complements the terminal session interface with additional control functions, e.g., for setting the baud rate. Because UART sessions are compatible to terminal sessions, a UART device driver can be used as both UART server and terminal server.

The event session interface is used to communicate low-level user-input events from the client to the server using synchronous bulk transfers (Section Synchronous bulk transfer). Such an event can be of one of the following types:

Use cases

• A GUI server provides an event service as an interface for supplying user input to the GUI.

• Drivers for user-input devices play the roles of event clients.

• Merging multiple streams of user input into one stream, using an event filter component.

• Virtual input devices can be realized as event clients that inject artificial input events to a GUI server or an event filter.

The capture session interface enables a client to obtain pixel data from a server. For example, a framebuffer driver plays the role of a capture client that obtains the pixel data to be displayed on screen from a GUI server.

The pixel data is communicated via a dataspace shared between server and client. The client (the driver) requests information about so-called dirty areas via periodic RPC calls from the server. The period of those calls is controlled by the driver and may ideally correspond to the physical screen refresh (vblank) rate, e.g., 60 times per second. Based on the returned dirty-area information, the client flushes the pixels from the shared buffer to the output device.

Use cases

• A framebuffer driver captures the pixels from a GUI server.

• A remote-desktop server application captures the screen of a GUI server.

Figure 1

A GUI session aggregates a virtual framebuffer, an input stream, and a session-local view stack.

The GUI session interface combines a virtual framebuffer and an input stream into a session. Technically, both the framebuffer and the input stream are aggregated as two distinct RPC interfaces as depicted in Figure 1. The input interface allows the client to obtain user-input events whereas the framebuffer interface is used for pixel output. Furthermore, the GUI session supplements the framebuffer with the notion of views, which allows for the creation of flexible multi-window user interfaces.

Framebuffer interface

The GUI client obtains access to the framebuffer as a dataspace, which is shared between client and server. The client may update the pixels within the dataspace at any time. Once a part of the framebuffer has been updated, the client informs the server by calling a refresh RPC function. Thereby, the framebuffer session interface employs a synchronous bulk transfer mechanism (Section Synchronous bulk transfer). To enable GUI clients to synchronize their operations with the refresh rate of the display, a client can register a handler for receiving display-synchronization events as asynchronous notifications (Section Asynchronous notifications).

View stack

A view is a rectangular area on screen that displays a portion of the client's virtual framebuffer. The position, size, and viewport of each view is defined by the client. Views can overlap, thereby creating a view stack. The stacking order of the views of one client can be freely defined by the client.

The size of the virtual framebuffer can be freely defined by the client but the required backing store must be provided in the form of session quota. Clients may request the screen mode of the physical framebuffer and are able to register a signal handler for mode changes of the physical framebuffer. This way, GUI clients are able to adapt themselves to changing screen resolutions.

Use cases

• The nitpicker GUI server allows multiple GUI applications to share the same framebuffer and input devices in a secure way.

• A window manager implementing the GUI session interface represents each view as a window with window decorations and a placement policy. The resizing of a window by the user is reflected to the client as a screen-mode change.

• A loader (Section Loader) virtualizes the GUI session interface for the loaded subsystem.

The platform session interface (on ARM-based devices) and the PCI session interface (on x86-based machines) provide the client with access to the devices present on the hardware platform. See Section Platform driver for more information on the role of platform drivers.

The block session interface allows a client to access a storage server at the block level. The interface is based on a packet stream (Section Asynchronous bulk transfer - packet streams). Each packet represents a block-access command, which can be either read or write. Thanks to the use of the packet-stream mechanism, the client can issue multiple commands at once and thereby hide access latencies by submitting batches of block requests. The server acknowledges each packet after completing the corresponding block-command operation.

The packet-stream interface for submitting commands is complemented by the info RPC function for querying the properties of the block device, i.e., the supported operations, the block size, and the block count. Furthermore, a client can call the sync RPC function to flush caches at the block server.

Session creation

At session-creation time, the client can dimension the size of the communication buffer as session argument. The server allocates the shared communication buffer from the session quota.

Use cases

• Block-device drivers implement the block-session interface.

• The part-block component requests a single block session, parses a partition table, and hands out each partition as a separate block session to its clients. There can be one client for each partition.

• File-system servers use block sessions as their back end.

The timer session interface provides a client with a session-local time source. A client can use it to schedule timeouts that are delivered as signals to a previously registered signal handler. Furthermore, the client can request the elapsed number of milliseconds since the creation of the timer session.

A NIC session represents a network interface that operates at network-packet level. Each session employs two independent packet streams (Section Asynchronous bulk transfer - packet streams), one for receiving network packets and one for transmitting network packets. Furthermore, the client can query the MAC address of the network interface.

Session creation

At session-creation time, the communication buffers of both packet streams are dimensioned via session arguments. The communication buffers are allocated by the server using the session quota provided by the client.

Use cases

• A NIC router provides multiple virtual NIC interfaces to its clients by managing a custom name space of virtual MAC addresses.

• A TCP/IP stack uses a NIC session as back end.

An uplink session is similar a NIC session with the difference that the roles of the end points are swapped. An uplink client is the one that provides a network interface (for instance, a NIC driver) whereas an uplink server is the one that uses that network interface.

In contrast to the NIC session, the MAC address and link state are defined by the client. The link state is reflected through the lifetime of an uplink session: The client requests the session only when the link state is up and closes it whenever the link state becomes down again. The MAC address is transmitted from the client to the server as a session-construction argument.

Use cases

• A network driver connects to a NIC router to appear as uplink.

The audio output interface allows for the transfer of audio data from the client to the server. One session corresponds to one channel. I.e., for stereo output, two audio-out sessions are required.

Session construction

At session-construction time, the client specifies the type of channel (e.g., front left) as session argument.

Interface design

For the output of streamed audio data, a codec typically decodes a relatively large portion of an audio stream and submits the sample data to a mixer. The mixer, in turn, mixes the samples of multiple sources and forwards the result to the audio driver. The codec, the mixer, and the audio driver are separate components. By using large buffer sizes between them, there is only very little context-switching overhead. Also, the driver can submit large buffers of sample data to the sound device without any further intervention needed. In contrast, sporadic sounds are used to inform the user about an immediate event. An example is the acoustic feedback to certain user input in games. The user ultimately expects that such sounds are played back without much latency. Otherwise the interactive experience would suffer. Hence, using large buffers between the audio source, the mixer, and the driver is not an option. The audio-out session interface was specifically designed to accommodate both corner cases of audio output.

Figure 2

The time-driven audio-out session interface uses shared memory to transfer audio frames and propagate progress information.

Similarly to the packet-stream mechanism described in Section Asynchronous bulk transfer - packet streams, the audio-out session interface depicted in Figure 2 employs a combination of shared memory and asynchronous notifications. However, in contrast to the packet-stream mechanism, it has no notion of ownership of packets. When using the normal packet-stream protocol, either the source or the sink is in charge of handling a given packet at a given time, not both. The audio-out session interface weakens this notion of ownership by letting the source update once submitted audio frames even after submitting them. If there are solely continuous streams of audio arriving at the mixer, the mixer can mix those large batches of audio samples at once and pass the result to the driver.

Figure 3

The mixer processes batches of incoming audio frames from multiple sources.

Now, if a sporadic sound comes in, the mixer checks the current output position reported by the audio driver, and re-mixes those portions that haven't been played back yet by incorporating the sporadic sound. So the buffer consumed by the driver gets updated with new data.

Figure 4

A sporadic occurring sound prompts the mixer to remix packets that were already submitted in the output queue.

Besides the way of how packets are populated with data, the second major difference to the packet-stream mechanism is its time-triggered mode of operation. The driver produces periodic signals that indicate the completeness of a played-back audio packet. This signal triggers the mixer to become active, which in turn serves as a time base for its clients. The current playback position is denoted alongside the sample data as a field in the memory buffer shared between source and sink.

Use cases

• The audio-out session interface is provided by audio drivers.

• An audio mixer combines incoming audio streams of multiple clients into one audio stream transferred to an audio driver.

The file-system session interface provides the client with a storage facility at the file and directory-level. Compared to the block session interface (Section Block), it operates on a higher abstraction level that is suited for multiplexing the storage device among multiple clients. Similar to the block session, the file-system session employs a single packet stream interface (Section Asynchronous bulk transfer - packet streams) for issuing read and write operations. This way, read and write requests can be processed in batches and even out of order.

In contrast to read and write operations that carry potentially large amounts of payload, the directory functions provided by the file-system session interface are synchronous RPC functions. Those functions are used for opening, creating, renaming, moving, deleting, and querying files, directories and symbolic links.

The directory functions are complemented with an interface for receiving notifications upon file or directory changes using asynchronous notifications.

Use cases

• A file-system operates on a block session to provide file-system sessions to its clients.

• A RAM file system keeps the directory structure and files in memory and provides file-system sessions to multiple clients. Each session may be restricted in different ways (such as the root directory as visible by the respective client, or the permission to write). Thereby the clients can communicate using the RAM file system as a shared storage facility but are subjected to an information-flow policy.

• A file-system component may play the role of a filter that transparently encrypts the content of the files of its client and stores the encrypted files at another file-system server.

• A pseudo file system may use the file-system interface as an hierarchic control interface. For example, a trace file system provides a pseudo file system as a front end to interact with core's TRACE service.

The loader session interface allows clients to dynamically create Genode subsystems to be hosted as children of a loader service. In contrast to a component that is spawning a new subsystem as an immediate child, a loader client has very limited control over the spawned subsystem. It can merely define the binaries and configuration to start, define the position where the loaded subsystem will appear on screen, and kill the subsystem. But it is not able to interfere with the operation of the subsystem during its lifetime.

Session creation

At session-creation time, the client defines the amount of memory to be used for the new subsystem as session quota. Once the session is established, the client equips the loader session with ROM modules that will be presented to the loaded subsystem. From the perspective of the subsystem, those ROM modules can be requested in the form of ROM sessions from its parent.

Visual integration of the subsystem

The loaded subsystem may implement a graphical user interface by creating a GUI session (Section GUI). The loader responds to such a session request by providing a locally implemented session. The loader subordinates the GUI session of the loaded subsystem to a GUI view (called parent view) defined by the loader client. The loader client can use the loader session interface to position the view relative to the parent-view position. Thereby, the graphical user interface of the loaded subsystem can be seamlessly integrated with the user interface of the loader client.

Use case

The most illustrative use case is the execution of web-browser plugins where neither the browser trusts the plugin nor the plugin trusts the browser (Section Ceding the parenthood).