Genode components overview

Genode comes with a growing number of components apparently scattered across various repositories. This document provides an overview of these components and outlines the systematics behind them.

The scope of this document is limited to the Genode main repository maintained by Genode Labs. Many additional components and device drivers can be found in the community-maintained Genode-World repository.

Categorization of components

Genode components usually fall into one of four categories, namely device drivers, resource multiplexers, protocol stacks, and applications. Each of them is briefly characterized as follows:

Device drivers

translate hardware resources into device-independent session interfaces. Naturally, a device driver is specific to a particular hardware platform. The hardware resources are accessed via core's IO_MEM, IO_PORT, and IRQ services. The functionality of the driver is made available to other system components via one of Genode's device-independent session interfaces, which are platform_session, capture_session, event_session, block_session, record_session, play_session, log_session, uplink_session, and timer_session (see os/include/ for the interface definitions). Those interfaces are uniform across hardware platforms and kernel base platforms. Usually, each device driver accommodates one client at a time.

Resource multiplexers

provide mechanisms to multiplex device resources to multiple clients. A typical resource multiplexer requests one of Genode's device-independent session interface (usually connected to a device driver) and, in turn, announces a service of the same kind. However, in contrast to a device driver, a resource multiplexer is able to serve more than one client at the same time.

Protocol stacks

translate low-level interfaces to higher-level interfaces (or sometimes vice versa). Typically, a protocol stack comes in the form of a library, which uses a device-independent session interface as back end and provides a high-level library interface as front end. However, protocol stacks also exist in the form of distinct components that implement translations between different session interfaces.

Applications

implement functionality using APIs as provided by protocol stacks.

Runtime environments

enable existing 3rd-party software to be executed as a Genode sub systems.

Device drivers

Device drivers usually reside in the src/drivers/ subdirectory of source-code repositories. The most predominant repositories hosting device drivers are os, dde_ipxe, dde_linux, pc. The main source tree is accompanied by a variety of optional source-code repositories, each hosting the support of a different SoC family such as NXP's i.MX, Allwinner, Xilinx Zynq, or RISC-V.

Repositories maintained by Genode Labs

https://github.com/orgs/genodelabs/repositories

Platform devices

os/src/drivers/platform/

Platform drivers for various platforms. On x86, the platform driver uses the PCI controller as found on x86 PC hardware. A client can probe for a particular device and request information about physical device resources (using the platform_device interface). I/O resources for MMIO regions, I/O ports, and interrupts can be requested by the provided device abstraction.

os/src/drivers/acpi/

On x86 platforms that use the APIC (namely Fiasco.OC, NOVA, and hw_x86_64) this simple ACPI parser traverses the ACPI tables and reports device-resource information (e.g., interrupt lines of PCI devices).

os/src/app/pci_decode/

A component that reports the physical information about PCI devices after parsing and initializing the PCI bus. The reported information is usually consumed by the platform driver.

os/src/app/smbios_decoder/

A component that parses SMBIOS information on x86 platforms and makes the result available as a report.

libports/src/app/acpica/

In addition to our ACPI base driver, the acpica component uses the ACPICA library to provide access to dynamic functions like battery states, events (e.g., notebook lid close and power buttons), as well as reset and power off. The componenten reports ACPI events and states as reports and itself responds to system state changes of certain configuration ROMs.

UART devices

The UART device drivers implement the UART-session interface.

os/src/drivers/uart/spec/pbxa9/

Driver for the PL011 UART as found on many ARM-based platforms.

os/src/drivers/uart/spec/x86/

Driver for the i8250 UART as found on PC hardware.

Framebuffer and input drivers

Framebuffer and input drivers are implemented as clients of the capture-session and event-session interfaces respectively.

os/src/drivers/ps2/x86/

Driver for the i8042 PS/2 controller as found in x86 PCs. It supports both mouse (including ImPS/2, ExPS/2) and keyboard.

os/src/drivers/ps2/pl050/

Driver for the PL050 PS/2 controller as found on ARM platforms such as VersatilePB. The physical base address used by the driver is obtained at compile time from a header file called pl050_defs.h. The version of the VersatilePB platform can be found at os/include/platform/vpb926/ and is made available to the driver via the SPECS machinery of the Genode build system.

libports/src/drivers/framebuffer/vesa/

Driver using VESA mode setting on x86 PCs. For more information, please refer to the README file in the driver directory.

libports/src/drivers/framebuffer/boot/

Driver for boot-time initialized framebuffers (e.g., UEFI GOP) discovered from the platform_info ROM

os/src/drivers/framebuffer/pl11x/

Driver for the PL110/PL111 LCD display.

os/src/drivers/framebuffer/sdl/

Serves as both framebuffer and input driver on Linux using libSDL. This driver is only usable on the Linux base platform.

os/src/drivers/framebuffer/virtio/

Driver for the Virtio virtual graphics device as supported by Qemu.

os/src/drivers/gpu/intel/

An Intel Graphics GPU multiplexer for Broadwell and newer.

pc/src/drivers/framebuffer/intel/

Framebuffer driver for Intel i915 compatible graphic cards based on the Linux Intel KMS driver.

pc/src/drivers/usb_host/

USB host-controller driver that provides an USB session interface to USB drivers.

dde_linux/src/drivers/usb_hid/

USB Human Interface Device driver using the USB session interface.

Timer drivers

The timer driver located at base/src/timer/ implements the timer-session interface. Technically, it is both a device driver (accessing a timer device) and a resource multiplexer (supporting multiple timer-session clients at the same time). Depending on the base platform, the implementation uses different time sources. Time sources are either hardware timers, a time source provided by the kernel, or a pseudo time source (busy):

nova

NOVA kernel semaphores

okl4_x86

Programmable Interval Timer (PIT) device

foc

IPC timeout

fiasco

IPC timeout

pistachio

Programmable Interval Timer (PIT) device

linux

nanosleep()

hw

kernel timer

sel4

PIT on x86, EPIT on Wandboard

Audio drivers

Audio drivers use the audio mixer's record session interface defined at os/include/record_session/ for audio output and optionally the play session interface os/include/play_session/ for audio input.

os/src/drivers/audio/spec/linux/

Uses ALSA as back-end on the Linux base platform and supports only playback.

dde_bsd/src/drivers/audio/

Sound drivers ported from OpenBSD. Currently, the repository includes support for Intel HD Audio as well as for Ensoniq AudioPCI (ES1370) compatible sound cards.

Block drivers

All block drivers implement the block-session interface defined at os/include/block_session/.

os/src/drivers/sd_card/pl180/

Driver for SD-cards connected via the PL180 device as found on the PBX-A9 platform.

os/src/drivers/sd_card/imx53/

Driver for SD-cards connected to the Freescale i.MX53 platform like the Quick Start Board or the USB armory device.

os/src/drivers/ahci/

Driver for SATA disks and CD-ROMs on x86 PCs.

os/src/drivers/nvme/

Driver for NVMe block devices on x86 PCs.

os/src/drivers/usb_block/

USB Mass Storage Bulk-Only driver using the USB session interface and provides a block-session interface.

Network interface drivers

All network interface drivers implement the NIC session interface defined at os/include/nic_session/.

os/src/drivers/nic/spec/linux/

Driver that uses a Linux tap device as back end. It is only useful on the Linux base platform.

os/src/drivers/nic/lan9118/

Native device driver for the LAN9118 network adaptor as featured on the PBX-A9 platform.

dde_ipxe/src/drivers/nic/

Device drivers ported from the iPXE project. Supported devices are Intel E1000 and pcnet32.

pc/src/drivers/nic/pc/

The PC NIC-driver component uses network driver code of the Linux kernel to drive common network cards as found in commodity PC hardware.

pc/src/drivers/wifi/

The wifi driver component is a port of the Linux mac802.11 stack, including the iwlwifi driver. It enables the use of Intel Wireless 6xxx and 7xxx cards.

dde_linux/src/drivers/usb_net/

USB network driver using the USB session interface.

Resource multiplexers

By convention, resource multiplexers are located at the src/server/ subdirectory of a source repository.

Framebuffer and input

Framebuffer and input devices can be multiplexed using the Nitpicker GUI server, which allows multiple clients to create and manage rectangular areas on screen. Nitpicker serves as broker between input devices, output devices, and graphical applications. It provides an event service for input drivers, a capture service for output drivers, and a GUI service for the applications. Each GUI session contains a virtual framebuffer and a virtual input interface. Nitpicker (including a README file) is located at os/src/server/nitpicker/.

Audio output

The audio mixer located at os/src/server/record_play_mixer/ allows for the routing and mixing of audio signals from play-session clients to record-session clients.

Networking

The NIC bridge located at os/src/server/nic_bridge/ multiplexes one NIC session to multiple virtual NIC sessions using a proxy-ARP implementation. Each client has to obtain a dedicated IP address visible to the physical network. DHCP requests originating from the virtual NIC sessions are delegated to the physical network.

The NIC router located at os/src/server/nic_router/ multiplexes one NIC session to multiple virtual NIC sessions by applying network address translation (NAT).

The NIC-uplink component located at os/src/server/nic_uplink/ connects a NIC client directly to a network driver (as uplink client) without routing.

Block

The block-device partition server at os/src/server/part_block/ reads the partition table of a block session and exports each partition found as separate block session. For using this server, please refer to the run script at os/run/part_block.run.

File system

The VFS file-system server allows multiple clients to concurrently access the same virtual file system. It is located at os/src/server/vfs/. The VFS can be assembled out of several builtin file-system types (like a RAM file system, or pseudo file systems for various Genode session interfaces) as well as external plugins such as rump (mounting file systems supported by the NetBSD kernel).

Terminal

The terminal_mux service located at gems/src/server/terminal_mux/ is able to provide multiple terminal sessions over one terminal-client session. The user can switch between the different sessions using a keyboard shortcut, which brings up an ncurses-based menu.

Protocol stacks

Protocol stacks come either in the form of separate components that translate one session interface to another, or in the form of libraries.

Separate components

os/src/server/gui_fb/

Translates a GUI session to a pair of framebuffer and input sessions. Each gui_fb instance is visible as a rectangular area on screen presenting a virtual frame buffer. The area is statically positioned. For more information, please refer to os/src/server/gui_fb/README.

gems/src/server/wm/

Window manager that implements the GUI session interface but manages each client view as a separate window. The window decorations are provided by a so-called decorator (e.g., gems/src/app/decorator/). The behaviour is defined by a so-called window layouter such as the floating window layouter located at gems/src/app/floating_window_layouter/.

demo/src/server/liquid_framebuffer/

Implements the same translation as gui_fb but by presenting an interactive window rather than a statically positioned screen area.

os/src/server/tar_rom/

Provides each file contained in a tar file obtained via Genode's ROM session as separate ROM session.

os/src/server/lx_fs/

A file system server that makes the file system of a Linux base platform available to Genode.

os/src/server/vfs_block/

Provides the content of a file obtained from a VFS as a block session, similar to the loop-mount mechanism on Linux

os/src/server/terminal_log/

Adapter for forwarding LOG messages to a terminal session.

os/src/server/log_terminal/

Adapter for forwarding terminal output to a LOG session.

demo/src/server/nitlog/

Provides a LOG session, printing log output on screen via a GUI session.

os/src/app/rom_logger/

The rom_logger component requests a ROM session and writes the content of the ROM dataspace to the LOG.

os/src/server/rom_filter/

The ROM filter provides a ROM module that depends on the content of other ROM modules steered by the filter configuration, e.g., dynamic switching between configuration variants dependent on the state of the system.

gems/src/server/file_terminal/

Provides terminal sessions that target files on a file system.

gems/src/server/terminal/

Provides a terminal session via a graphical terminal using a framebuffer session and an input session.

gems/src/server/tcp_terminal/

Provides one or multiple terminal sessions over TCP connections. For further information, refer to gems/src/server/tcp_terminal/README.

os/src/server/terminal_crosslink/

The terminal crosslink service allows to terminal clients to talk to each other.

os/src/server/fs_rom/

A ROM service that translates the File_system session interface to the ROM session' interface. Each request for a ROM file is handled by looking up an equally named file on the file system. Please refer to os/src/server/fs_rom/ for more information.

For use cases where ROMs are known to be static, the os/src/server/cached_fs_rom/ can be considered as a faster alternative to the regular fs_rom server. Note that cached_fs_rom is not supported in base-linux though.

os/src/server/chroot/

An intermediate file-system server that makes a sub directory of a file system available as the root of a file system handed out to its client.

os/src/server/dynamic_rom/

A simple ROM service that provides ROM modules that change in time according to a configured timeline.

os/src/server/report_rom/

A service that implements both the report session interface and the ROM session interface. It reflects incoming reports as ROM modules.

os/src/server/fs_report/

Report server that writes reports to file-systems

os/src/server/clipboard/

This component is both a report service and a ROM service. The clients of the report service can issue new clipboard content, which is then propagated to the clients of the ROM service according to a configurable information-flow policy.

os/src/server/event_filter/

A component that transforms and merges input events from multiple sources into a single event stream.

libports/src/app/acpi_event/

A component that transforms ACPI events into Genode input events.

gems/src/server/gui_fader/

A wrapper for nitpicker's GUI session interface that applies alpha-blending to the of views a GUI client.

os/src/server/black_hole/

Mockup implementation of Genode session interfaces.

dde_linux/src/app/wireguard/

Port of the Linux implementation of the WireGuard VPN as Genode component.

VFS plugins

VFS plugins are file-system drivers in the form of shared libraries that implement the VFS-plugin interface. They can be combined with any application based on Genode's C runtime, with the VFS server, and with non-POSIX components that use the Genode's VFS library directly.

os/src/lib/vfs/tap/

A VFS plugin that allows for packet-level access of a NIC or uplink session.

gems/src/lib/vfs/trace/

A VFS plugin that makes core's TRACE service accessible as a pseudo file system.

gems/src/lib/vfs/import/

A VFS plugin that pre-populates a VFS with initial content.

gems/src/lib/vfs/pipe/

A VFS plugin that provides bi-directional pipes for exchanging streamed data between components.

gems/src/lib/vfs/ttf/

A VFS plugin that makes rendered pixel data of the glyphs of Truetype fonts available as a pseudo file system.

libports/src/lib/vfs/jitterentropy/

A VFS plugin that provides random numbers based on the jitter of executing CPU instructions.

libports/src/lib/vfs/lwip/

A VFS plugin that uses the light-weight IP (lwIP) stack to provide a network socket interface as a pseudo file system.

dde_linux/src/lib/vfs/lxip/

A VFS plugin that uses the TCP/IP stack ported from the Linux kernel to provide a network socket interface as a pseudo file system.

libports/src/lib/vfs/fatfs/

A VFS plugin that allows for the mounting of FAT-formatted block devices.

os/src/lib/vfs/tap/

A VFS plugin for the interaction with raw network packets.

dde_rump/src/lib/vfs/rump/

A VFS plugin that enables the use of NetBSD's file-system drivers such as ext2 or msdos.

Libraries

libports/lib/mk/libc/

C runtime ported from FreeBSD.

libports/lib/mk/stdcxx/

Standard C++ library

libports/lib/mk/mesa_api/

Mesa OpenGL API with backends for software rasterization (egl_swrast) and Intel Graphics (egl_i965)

libports/lib/mk/mupdf/

PDF rendering engine.

libports/lib/mk/ncurses/

Library for implementing pseudo-graphical applications (i.e., VIM) that run on a text terminal.

libports/lib/mk/qt5_*/

Qt5 framework, using GUI session and NIC session as back end.

libports/lib/mk/vfs_jitterentropy.mk

A VFS plugin that makes a jitter-based random-number generator available as a file within the process-local VFS.

libports/lib/mk/libarchive.mk

Library providing a common interface to a variety of archive formats.

libports/lib/mk/lz4.mk

Library for processing LZ4 lossless compression archives.

libports/lib/mk/liblzma.mk

Library for processing LZMA archives.

libports/lib/mk/libgcrypt.mk

GnuPG library for OpenPGP processing, e.g., signature verification.

Applications

Applications are Genode components that use other component's services but usually do not provide services. They are typically located in the src/app/ subdirectory of a repository. Most applications come with README files located in their respective directory.

gems/src/app/backdrop/

GUI client application that sets a composition of PNG images as desktop background.

demo/src/app/launchpad/

Graphical application for interactively starting and killing subsystems.

demo/src/app/scout/

Graphical hypertext browser used for Genode's default demonstration scenario.

ports/src/app/gdb_monitor/

Application that allows the debugging of a process via GDB over a remote connection.

libports/src/app/qt5/qt_launchpad/

Graphical application starter implemented using Qt.

libports/src/app/qt5/examples/

Several example applications that come with Qt.

os/src/app/sequence/

Simple utility to serialize the execution of multiple components

ports/src/noux-pkg/

Ports of popular commandline-based Unix software such as VIM, bash, coreutils, binutils, gcc, findutils, and netcat. The programs are supposed to be executed within the Noux runtime environment.

ports/src/app/lighttpd/

Lighttpd is a fast and feature-rich web server. The port of lighttpd uses a file-system session to access the website content and the web-server configuration.

os/src/app/trace_logger/

Convenient, runtime-configurable frontend to the tracing facility.

os/src/app/rom_reporter/

The ROM-reporter component requests a ROM session and reports the content of the ROM dataspace to a report session with the same label as the ROM session.

os/src/app/log_core/

Component transforming core and kernel output to Genode LOG output.

Package-management components

gems/src/app/depot_query/

Tool for querying subsystem information from a depot.

gems/src/app/depot_download_manager/

Tool for managing the download of depot content.

gems/src/app/depot_deploy/

Subsystem init configuration generator based on blueprints.

gems/src/app/depot_remove/

Tool for the orderly removal of depot content.

libports/src/app/fetchurl/

A runtime-configurable frontend to the libcURL library for downloading content.

libports/src/app/extract/

Tool for extracting archives using libarchive.

ports/src/app/verify/

This component verifies detached OpenPGP signatures using libgcrypt.

Runtime environments

os/src/server/loader/

A service that allows the creation and destruction of Genode subsystems via a session interface. For further information, refer to os/src/server/loader/README.

ports/src/virtualbox6/

VirtualBox running on top of the NOVA hypervisor.

os/src/server/vmm/

A virtual machine monitor that is based on hardware-assisted virtualization of ARM platforms. It is supported on the base-hw kernel only.

os/src/server/cpu_balancer/

The CPU balancer intercepts the interaction of components with core's low-level services to migrate threads dynamically between CPU cores.