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:

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