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
Input session interface
An input session (Section Input) represents a stream of user-input events.
Framebuffer session interface
Nitpicker 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 session interface
Audio-out session interface
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.