OS-level session interfaces

Report session interface

Report sessions (Section Report) allow a component to propagate internal state to the outside. The most prominent use case is the realization of publisher-subscriber communication schemes as discussed in Section Publishing and subscribing.

Report::Session

Report::Connection

The client-side Reporter is a convenient front end for the use of a report connection to propagate XML-formed data.

Genode::Reporter

The Expanding_reporter further streamlines the generation of reports by eliminating the burden of handling Buffer_exceeded exceptions as thrown by the Xml_generator from components that generate reports. Such exceptions are easy to miss because reports are often small at testing time but become larger in complex scenarios. Whenever the report exceeds the current buffer size, the expanding reporter automatically upgrades the report session as needed. Note that such an upgrade consumes RAM quota. For components that strictly account RAM consumption to clients, the regular Reporter is preferable. However, in most cases - where reports are not accounted per client but to the component itself - the Expanding_reporter should better be used. Besides the builtin support for growing the report buffer, the expanding reporter alleviates the need to explicitly enable reports. In contrast to the Reporter, it is implicitly enabled at construction time.

Genode::Expanding_reporter

Terminal and UART session interfaces

A terminal session (Section Terminal and UART) is a bi-directional communication channel. The UART session interface supplements the terminal session interface with a facility to parametrize UART configuration parameters

Terminal::Session

Terminal::Connection

Uart::Session

Uart::Connection

Event session interface

An event session (Section Event) represents a stream of user-input events from client to server.

Event::Session

Event::Connection

Capture session interface

Framebuffer::Mode

Capture::Session

Capture::Connection

GUI session interface

The GUI session described in Section GUI comprises a virtual framebuffer, a stream of user-input events, and a so-called view stack, which defines how portions of the virtual framebuffer are composed on screen.

Gui::Session

Gui::Connection

Framebuffer::Session

Input::Session

Capture session interface

Framebuffer::Mode

Capture::Session

Capture::Connection

Platform session interface

Platform::Device

Platform::Session

Block session interface

The block-session interface provides block-device-level access to persistent storage (Section Block). At the client side, the Block::Connection provides a job interface to issue arbitrary block requests to a server in an asynchronous fashion. At the server side, the Block::Request_stream API facilitates the implementation of asynchronously block services such as block-device drivers. Both client and server share the same notion of a Block::Request.

Block::Operation

Block::Request

Client-side block connection


Block::Connection

Server-side block-request stream

To simplify the implementation of robust and scalable block servers, there exists a server-side block-session front end called block-request stream. It is designed with the following considerations:

The use of the block-request stream API is illustrated by the example at os/src/test/block_request_stream/.

Block::Request_stream

Timer session interface

Timer::Session

Timer::Connection

The Periodic_timeout and One_shot_timeout classes provide a convenient API for implementing timeout handlers, following the same pattern as used for signal handlers (Section Signalling).

Timer::Periodic_timeout

Timer::One_shot_timeout

NIC and uplink session interfaces

Nic::Session

Nic::Connection

Uplink::Session

Uplink::Connection

Record and play session interfaces

The record and play session (Section Audio recording and playing) interfaces allow for the streaming of audio data between components. Each session corresponds to a channel. Hence, stereo output requires two play sessions. Both services are typically provided by a mixer that routes data streams from play clients to record clients. Sample values are represented as floating-point numbers and communicated over shared memory.

Play::Session

Play::Connection

Record::Session

Record::Connection

File-system session interface

The file-system session (Section File system) interface provides to store and retrieve data in the form of files organized in a hierarchic directory structure. Directory operations are performed via a synchronous RPC interface whereas the actual read and write operations are performed asynchronously using a packet stream.

repos/os/include/file_system_session/file_system_session.h

A file-system client issues read or write requests by submitting packet descriptors to the file-system session's packet stream. Each packet descriptor contains all parameters of the transaction including the type of operation, the seek offset, and the length.

File_system::Packet_descriptor

File_system::Session

File_system::Connection

The file-system session's status and control operations use the compound structures Status and Control as arguments. The format of the data retrieved by reading a directory node is defined by the Directory_entry.

File_system::Status

File_system::Control

File_system::Directory_entry

Pin state and control session interfaces

A pin-state or pin-control session (Section Pin state and control) allows its client to interact with an individual GPIO pin. The pin is referred to by the client's session label.

Pin_state::Session

Pin_state::Connection

Pin control

The state RPC function sets the digital output to high or low, which is the most common use.

To accommodate the time-multiplexed operation of a pin as output and input, the yield RPC function switches the pin to high-impedance. It can thereby be driven as input pin and its state can be monitored via a separate pin-state session referring to the same pin as the pin-control session. This is useful for implementing two-wire protocols like I2C in software.

Pin_control::Session

Pin_control::Connection