API

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:

1. API primitives
   1. Capability types
   2. Sessions and connections
   3. Dataspace interface
2. Component execution environment
   1. Interface to the component's environment
   2. Parent interface
3. Entrypoint
4. Region-map interface
5. Session interfaces of the base API
   1. PD session interface
   2. ROM session interface
   3. RM session interface
   4. CPU session interface
   5. IO_MEM session interface
   6. IO_PORT session interface
   7. IRQ session interface
   8. LOG session interface
6. OS-level session interfaces
   1. Report session interface
   2. Terminal and UART session interfaces
   3. Event session interface
   4. Capture session interface
   5. GUI session interface
   6. Capture session interface
   7. Platform session interface
   8. Block session interface
   9. Timer session interface
   10. NIC and uplink session interfaces
   11. Record and play session interfaces
   12. File-system session interface
   13. Pin state and control session interfaces
7. Fundamental types
   1. Integer types
   2. Exception types
   3. Exception-less error handling
   4. C++ supplements
8. Data structures
   1. List and registry
   2. Fifo queue
   3. AVL tree
   4. Dictionary
   5. ID space
   6. Bit array
9. Object lifetime management
   1. Thread-safe weak pointers
   2. Late and repeated object construction
10. Physical memory allocation
11. Component-local allocators
    1. Slab allocator
    2. AVL-tree-based best-fit allocator
    3. Heap and sliced heap
    4. Bit allocator
12. String processing
    1. Basic string operations
    2. Tokenizing
    3. Diagnostic output
    4. Obtaining backtraces
    5. Unicode handling
13. Multi-threading and synchronization
    1. Threads
    2. Inter-thread synchronization
14. Signalling
15. Remote procedure calls
    1. RPC mechanism
    2. Transferable argument types
    3. Throwing C++ exceptions across RPC boundaries
    4. RPC interface inheritance
    5. Casting capability types
    6. Non-virtual RPC interface functions
    7. Limitations of the RPC mechanism
    8. Root interface
    9. Server-side policy handling
    10. Packet stream
16. XML processing
    1. XML parsing
    2. XML generation
    3. XML-based data models
17. Component management
    1. Shared objects
    2. Child management
    3. Composition of subsystems
18. Utilities for user-level device drivers
    1. Register declarations
    2. Memory-mapped I/O