Common session interfaces

The core services described in Section Core - the root of the component tree principally enable the creation of a recursively structured system. However, their scope is limited to the few low-level resources provided by core, namely processing time, memory, and low-level device resources. Device drivers (Section Device drivers) and protocol stacks (Section Protocol stacks) transform those low-level resources into higher-level resources. Analogously to how core's low-level resources are represented by the session interfaces of core's services, higher-level resources are represented by the session interfaces provided by device drivers and protocol stacks. In principle, each device driver could introduce a custom session interface representing the particular device. But as discussed in the introduction of Chapter Components, a low number of orthogonal session interfaces is desirable to maximize the composability of components. This section introduces the common session interfaces that are used throughout Genode.

Read-only memory (ROM)

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.


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

Terminal and UART

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


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:

press or release

of a button or key. Each physical button (such as a mouse button) or key (such as a key on a keyboard) is represented by a unique value. At the event-session level, key events are reported as raw hardware events. They are reported without a keyboard layout applied and without any interpretation of meta keys (like shift, alt, and control). This gives the consumer of events the flexibility to handle arbitrary combinations of keys.

A press event may be annotated with an optional character representation of the pressed key in the form of a Unicode codepoint. Such events are not generated by low-level device drivers but by a higher-level service - like the event-filer component - that applies keyboard-layout rules to sequences of low-level events. Such annotated press events can be readily consumed by components that operate on textual input rather than low-level hardware events.

relative motion

of pointer devices such as a mouse. Such events are generated by device drivers.

absolute motion

of pointer devices such as a touch screen or graphics tablet. Furthermore absolute motion events are generated for virtual input devices such as a system-global pointer position maintained by the GUI server and reported to hovered GUI applications.

wheel motion

of scroll wheels in vertical and horizontal directions.


of the session. Focus events are artificially generated by GUI servers to indicate a gained or lost keyboard focus of a GUI application. The application may respond to such an event by changing its graphical representation accordingly.


of the pointer position. Similar to focus events, leave events are artificially generated by GUI servers to indicate a lost pointer focus.

Use cases


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


Figure 1 img/gui_session
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 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.

Pin state and control

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


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


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

Audio recording and playing

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

File system

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