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.

The platform session interface provides the client with access to the devices present on the hardware platform and assigned to the client. One platform session may comprise multiple devices. See Section Platform driver for more information about the role of the platform driver.

The pin-state and pin-control session interfaces are designated for interacting with general-purpose I/O (GPIO) pins. Each session corresponds to an individual pin. A pin-state client is able to monitor the state of an input pin whereas a pin-control client can define the digital signal level of an output pin. Even though a client of a pin session is able to interact with a pin, it has no authority over system-critical pin configurations nor does it need to refer to any physical properties of the pin like the GPIO bank or pin number.

The assignment of sessions to physical pins is in the hands of the pin driver and defined by the pin-driver's configuration. As each pin corresponds to a separate session, per-pin access control is naturally attained by Genode's regular session-routing and server-side policy-selection paradigms. The pin-driver's policy maps the session labels of its clients to physical pins and guards the configuration the physical pins regarding the I/O direction, pull up/down, or special-function selection.

A pin driver usually provides an IRQ service in addition to the pin-state and pin-control services. This IRQ service allows a client to receive notifications of a change of the signal level of a GPIO pin.

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 record and play session interfaces enable audio-processing components to stream audio data across component boundaries. A record session is used to obtain audio whereas a play session is used to submit generated audio data. Both session interfaces use shared memory for the transfer of audio data. The services are typically provided by a mixer component. The mixer routes and mixes audio signals produced by play clients to record clients according to its configuration. Typical play clients are an audio player or a microphone driver whereas typical record clients are an audio recorder or an audio-output driver. Note that audio drivers as well as audio applications are mere clients of the mixer. This architecture allows for the dynamic starting, removal, and restarting of a driver, of even multiple drivers.

Both play and record clients are expected to operate periodically. The number of samples produced per period is up to each client and does not need to be constant over time. The mixer infers the used sample rates and periods by observing the behavior of the clients. Sample rates between play and record clients are converted automatically.

Multi-channel playing and recording are realized by one session per channel whereas one channel is used to drive the time allocation while all further channels merely enqueue/obtain data into/from their respective sessions without any synchronous interplay with the mixer.

Session construction

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

Use cases

• The record and play session interfaces are provided by an audio mixer.

• An audio-output driver obtains sample data from the mixer using two record sessions for the left and right channels respectively, and converts the sample data into the format expected by the audio device.

• An audio-input driver submits data sampled from the microphone to the mixer via a play session.

• A multi-channel audio player uses one play session for each channel.

• A graphical oscilloscope uses a record session to get hold of the data to display.

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.