Functional specification
This chapter complements the architectural information of Chapters Architecture and Components with a thorough description of the framework's C++ programming interface. The material is partially generated from the source code, specifically the public header files of the base and os source-code repositories. The location of the headers in either both repositories depends on role of the respective header. Only if the interface is fundamentally required by the core component or by the base framework itself, it is contained in the base repository. Otherwise, the header is found in the os repository.
Scope of the API
The Genode API covers everything needed by Genode to be self-sufficient without any dependency on 3rd-party code. It does not even depend on a C runtime. It is possible to create components that solely use the raw Genode API, as is the case for the ones hosted within the repos/os/ repository. Because such components do not rely on any library code except for the low-complexity Genode base libraries, they are relatively easy to evaluate. That said, the API must not be mistaken as an application-level API. It does not present an alternative to established application-level libraries like the standard C++ library. For example, even though the framework contains a few utilities for processing strings, those utilities do merely exist to support the use cases present in Genode.
General conventions
The functional specification adheres to the following general conventions:
-
Static member functions are called class functions. All other member functions are called methods.
-
Both structs and classes are referred to as classes. There is no distinction between both at the API level.
-
Constant functions with no argument and a return value are called accessors. Technically, they are "getters" but since Genode does not have any "setters", accessors are synonymous to "getters". Because those functions are so simple, they are listed in the class overview and are not described separately.
-
Classes that merely inherit other classes are called sub types. In contrast to the use of a typedef, such classes are not mere name aliases but represent a new type. The type is compatible to the base class but not vice versa. For example, exception types are sub types of the Exception class.
-
Namespace-wide information is presented with a light yellow background.
-
Each non-trivial class is presented in the form of a class diagram on a blue-shaded background. The diagram shows the public base classes and the list of public class functions and methods. If the class is a template, the template arguments are annotated at the top-right of corner of the class. If the class represents an RPC interface, an information box is attached. The methods listed in the diagram can be used as hyperlinks to further descriptions if available.
-
Method descriptions are presented on a green-shaded background, global functions are presented on an orange-shaded background.
-
The directory path presented under "Header" sections is a hyperlink to the corresponding source code at GitHub.
Content:
- API primitives
- Component execution environment
- Entrypoint
- Region-map interface
- Session interfaces of the base API
- OS-level session interfaces
- Report session interface
- Terminal and UART session interfaces
- Event session interface
- Capture session interface
- GUI session interface
- Capture session interface
- Platform session interface
- Block session interface
- Timer session interface
- NIC and uplink session interfaces
- Audio-out session interface
- File-system session interface
- Report session interface
- Fundamental types
- Data structures
- Object lifetime management
- Physical memory allocation
- Component-local allocators
- String processing
- Multi-threading and synchronization
- Signalling
- Remote procedure calls
- XML processing
- Component management
- Utilities for user-level device drivers