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.
The client-side Reporter is a convenient front end for the use of a report connection to propagate XML-formed data.
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.
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
Event session interface
An event session (Section Event) represents a stream of user-input events from client to server.
Capture session interface
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.
Capture session interface
Platform session interface
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.
Client-side 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:
-
It anticipates the asynchronous operation of block servers by default. Using the API, such servers - in particular block-device drivers - can be implemented as state machines triggered by client requests and device interrupts.
-
It reinforces the memory safety of the server code by not returning any pointers or references.
-
It relieves the server developers from handling special cases (like a congested acknowledgement queue) while being flexible enough to accommodate different categories of components like drivers, resource multiplexers (part_block), and bump-in-the-wire components in a natural way.
-
It naturally supports the batching of requests as well as zero-copy (device DMA directly into the client's communication buffer).
The use of the block-request stream API is illustrated by the example at os/src/test/block_request_stream/.
Timer session interface
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).
NIC and uplink session interfaces
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.
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
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.
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 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.