Merge branch 'ealan' into tasking-profiler

Adding print_vgpu_bench method for printing bench data from vgpu
ô

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "repos/dde_uos-intel-gpgpu/src/uos-intel-gpgpu"]
+	path = repos/dde_uos-intel-gpgpu/src/uos-intel-gpgpu
+	url = https://ess.cs.uos.de/git/software/uos-intel-gpgpu.git

.vscode/c_cpp_properties.json

@@ -0,0 +1,46 @@
+{
+    "configurations": [
+        {
+            "name": "EalánOS",
+            "includePath": [
+                "${workspaceFolder}/depot/genodelabs/api/libc/**",
+                "${workspaceFolder}/depot/genodelabs/api/stdcxx/**",
+                "${workspaceFolder}/repos/base/**",
+                "${workspaceFolder}/repos/base-nova/**",
+                "${workspaceFolder}/repos/**"
+            ],
+            "defines": [
+                "__GENODE__",
+                "__FreeBSD__=12",
+                "_GLIBCXX_HAVE_MBSTATE_T",
+                "_GLIBCXX_ATOMIC_BUILTINS_4",
+                "_GLIBCXX_NO_OBSOLETE_ISINF_ISNAN_DYNAMIC"
+            ],
+            "compilerPath": "/usr/local/genode/tool/21.05/bin/genode-x86-g++",
+            "cStandard": "gnu17",
+            "cppStandard": "gnu++17",
+            "intelliSenseMode": "${default}",
+            "compilerArgs": [
+                "-nostdinc",
+                "-m64",
+                "-mcmodel=large",
+                "-MMD",
+                "-MP",
+                "-MT"
+            ],
+            "configurationProvider": "ms-vscode.cmake-tools"
+        },
+        {
+            "name": "Genode",
+            "includePath": [
+                "${workspaceFolder}/**"
+            ],
+            "defines": [],
+            "compilerPath": "/usr/bin/clang",
+            "cStandard": "c17",
+            "cppStandard": "c++14",
+            "intelliSenseMode": "linux-clang-x64"
+        }
+    ],
+    "version": 4
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "files.associations": {
+        "stop_token": "cpp",
+        "*.tcc": "cpp",
+        "initializer_list": "cpp",
+        "streambuf": "cpp",
+        "tuple": "cpp",
+        "memory": "cpp"
+    },
+    "vscode-as-git-mergetool.settingsAssistantOnStartup": false,
+    "makefile.makeDirectory": "build/x86_64"
+}

README

@@ -4,17 +4,15 @@
                       =================================
 
 
-This is the source code of Genode, which is a framework for creating
-component-based operating systems. It combines capability-based security,
-microkernel technology, sandboxed device drivers, and virtualization with
-a novel operating system architecture. For a general overview about the
-architecture, please refer to the project's official website:
+This is the source tree of the reference implementation of the Genode OS
+architecture. For a general overview about the architecture, please refer to
+the project's official website:
 
-:Website for the Genode OS Framework:
+:Official project website for the Genode OS Framework:
 
   [https://genode.org/documentation/general-overview]
 
-Genode-based operating systems can be compiled for a variety of kernels: Linux,
+The current implementation can be compiled for 8 different kernels: Linux,
 L4ka::Pistachio, L4/Fiasco, OKL4, NOVA, Fiasco.OC, seL4, and a custom "hw"
 microkernel for running Genode without a 3rd-party kernel. Whereas the Linux
 version serves us as development vehicle and enables us to rapidly develop the
@@ -24,7 +22,7 @@ one. If a microkernel pretended to be fit for all use cases, it wouldn't be
 "micro". Hence, all microkernels differ in terms of their respective features,
 complexity, and supported hardware architectures.
 
-Genode allows for the use of each of the supported kernels with a rich set of
+Genode allows the use of each of the kernels listed above with a rich set of
 device drivers, protocol stacks, libraries, and applications in a uniform way.
 For developers, the framework provides an easy way to target multiple different
 kernels instead of tying the development to a particular kernel technology. For
@@ -39,7 +37,7 @@ Documentation
 #############
 
 The primary documentation is the book "Genode Foundations", which is available
-on the front page of the Genode website:
+on the front page of Genode website:
 
 :Download the book "Genode Foundations":
 
@@ -81,6 +79,11 @@ The source tree is composed of the following subdirectories:
   Source-code management tools and scripts. Please refer to the README file
   contained in the directory.
 
+:'depot':
+
+  Directory used by Genode's package-management tools. It contains the public
+  keys and download locations of software providers.
+
 
 Additional hardware support
 ###########################
@@ -105,32 +108,13 @@ system scenarios.
   [https://github.com/genodelabs/genode-world]
 
 
-Community blog
-##############
-
-Genodians.org presents ideas, announcements, experience stories, and tutorials
-around Genode, informally written by Genode users and developers.
-
-:Genodians.org:
-
-  [https://genodians.org]
-
-
 Contact
 #######
 
-The community forum is organized by Genode users to help newcomers, share ideas
-and experiences, and discuss Genode-related projects.
+The best way to get in touch with Genode developers and users is the project's
+mailing list. Please feel welcome to join in!
 
-:Community forum:
-
-  [https://genode.discourse.group]
-
-The mailing list is the primary way for reaching out to Genode's core
-developers, for receiving announcements, and for the project's annual road-map
-discussion.
-
-:Genode Mailing List:
+:Genode Mailing Lists:
 
   [https://genode.org/community/mailing-lists]
 

README.md

@@ -0,0 +1,24 @@
+# EalánOS — An Operating System for Heterogeneous Many-core Systems
+
+EalánOS is a research operating system, based on the [Genode OS Framework](https://genode.org/), that explores new architectural designs and resource management strategies for many-core systems with heterogeneous computing and memory resources. It is a reference implementation of the [MxKernel](https://mxkernel.org/) architecture.
+
+## MxKernel Architecture
+The MxKernel is a new operating system architecture inspired by many-core operating systems, such as [FOS](https://dl.acm.org/doi/abs/10.1145/1531793.1531805) and [Tesselation](https://www.usenix.org/event/hotpar09/tech/full_papers/liu/liu_html/), as well as hypervisors, exokernels and unikernels.
+Novel approaches of the MxKernel include the use of tasks, short-lived closed units of work, instead of threads as control-flow abstraction, and the concept of elastic cells as process abstraction. The architecture has first been described in the paper [MxKernel: Rethinking Operating System Architecture for Many-core Hardware](https://sites.google.com/site/sfma2019eurosys/Program/sfma-mxkernel.pdf?attredirects=0) presented at the [9th Workshop on Systems for Multi-core and Heterogeneous Architectures](https://sites.google.com/site/sfma2019eurosys/). 
+
+## Task-based programming
+EalánOS promotes task-parallel programming by including the [MxTasking](https://github.com/jmuehlig/mxtasking.git) task-parallel runtime library. MxTasking improves on the common task-parallel programming paradigm by allowing tasks to be annotated with hints about the tasks behavior, such as memory accesses. These annotations are used by the runtime environment to implement advanced features, like automatic prefetching of data and automatic synchronization of concurrent memory accesses.
+
+## Documentation
+Because EalánOS is based on Genode, the primary documentation, for now, can be found in the book [Genode Foundations](https://genode.org/documentation/genode-foundations-22-05.pdf).
+
+## Features added to Genode
+EalánOS extends the Genode OS framework by functionality needed and helpful for many-core systems with non-uniform memory access (NUMA), such as
+- A topology service that allows to query NUMA information from within a Genode component.
+- A port of [MxTasking](https://github.com/jmuehlig/mxtasking.git), a task-based framework designed to aid in developing parallel applications.
+- (WiP) A extension of Genode's RAM service that enables applications to allocate memory from a specific NUMA region, similar to libnuma's `numa_alloc_on_node`, and thus improve NUMA-locality of internal data objects.
+- (WiP) An interface for using Hardware Performance Monitoring Counters inside Genode components. Currently, performance counters are only implemented for AMD's Zen1 microarchitecture.
+
+### Acknowledgement
+The work on EalánOS and the MxKernel architecture is supported by the German Research Foundation (DFG) as part of the priority program 2037 "[Scalable Data Management on Future Hardware](https://dfg-spp2037.de/)" under Grant numbers SP968/9-1 and SP968/9-2. 
+The MxTasking framework is developed as part of the same DFG project at the [DBIS group at TU Dortmund Universitiy](http://dbis.cs.tu-dortmund.de/cms/de/home/index.html)  and funded under Grant numbers TE1117/2-1.

VERSION

@@ -1 +1 @@
-24.11
+22.08

doc/build_system.txt

@@ -0,0 +1,517 @@
+
+
+                     =======================
+                     The Genode build system
+                     =======================
+
+
+                          Norman Feske
+
+Abstract
+########
+
+The Genode OS Framework comes with a custom build system that is designed for
+the creation of highly modular and portable systems software. Understanding
+its basic concepts is pivotal for using the full potential of the framework.
+This document introduces those concepts and the best practises of putting them
+to good use. Beside building software components from source code, common
+and repetitive development tasks are the testing of individual components
+and the integration of those components into complex system scenarios. To
+streamline such tasks, the build system is accompanied with special tooling
+support. This document introduces those tools.
+
+
+Build directories and repositories
+##################################
+
+The build system is supposed to never touch the source tree. The procedure of
+building components and integrating them into system scenarios is done at
+a distinct build directory. One build directory targets a specific platform,
+i.e., a kernel and hardware architecture. Because the source tree is decoupled
+from the build directory, one source tree can have many different build
+directories associated, each targeted at another platform.
+
+The recommended way for creating a build directory is the use of the
+'create_builddir' tool located at '<genode-dir>/tool/'. By starting the tool
+without arguments, its usage information will be printed. For creating a new
+build directory, one of the listed target platforms must be specified. 
+Furthermore, the location of the new build directory has to be specified via
+the 'BUILD_DIR=' argument. For example:
+
+! cd <genode-dir>
+! ./tool/create_builddir linux_x86 BUILD_DIR=/tmp/build.linux_x86
+
+This command will create a new build directory for the Linux/x86 platform
+at _/tmp/build.linux_x86/_.
+
+
+Build-directory configuration via 'build.conf'
+==============================================
+
+The fresh build directory will contain a 'Makefile', which is a symlink to
+_tool/builddir/build.mk_. This makefile is the front end of the build system
+and not supposed to be edited. Beside the makefile, there is a _etc/_
+subdirectory that contains the build-directory configuration. For most
+platforms, there is only a single _build.conf_ file, which defines the parts of
+the Genode source tree incorporated in the build process. Those parts are
+called _repositories_.
+
+The repository concept allows for keeping the source code well separated for
+different concerns. For example, the platform-specific code for each target
+platform is located in a dedicated _base-<platform>_ repository. Also, different
+abstraction levels and features of the system are residing in different
+repositories. The _etc/build.conf_ file defines the set of repositories to
+consider in the build process. At build time, the build system overlays the
+directory structures of all repositories specified via the 'REPOSITORIES'
+declaration to form a single logical source tree. By changing the list of
+'REPOSITORIES', the view of the build system on the source tree can be altered.
+The _etc/build.conf_ as found in a fresh created build directory will list the
+_base-<platform>_ repository of the platform selected at the 'create_builddir'
+command line as well as the 'base', 'os', and 'demo' repositories needed for
+compiling Genode's default demonstration scenario.  Furthermore, there are a
+number of commented-out lines that can be uncommented for enabling additional
+repositories.
+
+Note that the order of the repositories listed in the 'REPOSITORIES' declaration
+is important. Front-most repositories shadow subsequent repositories. This
+makes the repository mechanism a powerful tool for tweaking existing repositories:
+By adding a custom repository in front of another one, customized versions of
+single files (e.g., header files or target description files) can be supplied to
+the build system without changing the original repository.
+
+
+Building targets
+================
+
+To build all targets contained in the list of 'REPOSITORIES' as defined in
+_etc/build.conf_, simply issue 'make'. This way, all components that are
+compatible with the build directory's base platform will be built. In practice,
+however, only some of those components may be of interest. Hence, the build
+can be tailored to those components which are of actual interest by specifying
+source-code subtrees. For example, using the following command
+! make core server/nitpicker
+the build system builds all targets found in the 'core' and 'server/nitpicker'
+source directories. You may specify any number of subtrees to the build
+system. As indicated by the build output, the build system revisits
+each library that is used by each target found in the specified subtrees.
+This is very handy for developing libraries because instead of re-building
+your library and then your library-using program, you just build your program
+and that's it. This concept even works recursively, which means that libraries
+may depend on other libraries.
+
+In practice, you won't ever need to build the _whole tree_ but only the
+targets that you are interested in.
+
+
+Cleaning the build directory
+============================
+
+To remove all but kernel-related generated files, use
+! make clean
+
+To remove all generated files, use
+! make cleanall
+
+Both 'clean' and 'cleanall' won't remove any files from the _bin/_
+subdirectory. This makes the _bin/_ a safe place for files that are
+unrelated to the build process, yet required for the integration stage, e.g.,
+binary data.
+
+
+Controlling the verbosity of the build process
+==============================================
+
+To understand the inner workings of the build process in more detail, you can
+tell the build system to display each directory change by specifying
+
+! make VERBOSE_DIR=
+
+If you are interested in the arguments that are passed to each invocation of
+'make', you can make them visible via
+
+! make VERBOSE_MK=
+
+Furthermore, you can observe each single shell-command invocation by specifying
+
+! make VERBOSE=
+
+Of course, you can combine these verboseness toggles for maximizing the noise.
+
+
+Enabling parallel builds
+========================
+
+To utilize multiple CPU cores during the build process, you may invoke 'make'
+with the '-j' argument. If manually specifying this argument becomes an
+inconvenience, you may add the following line to your _etc/build.conf_ file:
+
+! MAKE += -j<N>
+
+This way, the build system will always use '<N>' CPUs for building.
+
+
+Caching inter-library dependencies
+==================================
+
+The build system allows to repeat the last build without performing any
+library-dependency checks by using:
+
+! make again
+
+The use of this feature can significantly improve the work flow during
+development because in contrast to source-codes, library dependencies rarely
+change. So the time needed for re-creating inter-library dependencies at each
+build can be saved.
+
+
+Repository directory layout
+###########################
+
+Each Genode repository has the following layout:
+
+  Directory  | Description
+ ------------------------------------------------------------
+  'doc/'     | Documentation, specific for the repository
+ ------------------------------------------------------------
+  'etc/'     | Default configuration of the build process
+ ------------------------------------------------------------
+  'mk/'      | The build system
+ ------------------------------------------------------------
+  'include/' | Globally visible header files
+ ------------------------------------------------------------
+  'src/'     | Source codes and target build descriptions
+ ------------------------------------------------------------
+  'lib/mk/'  | Library build descriptions
+
+
+Creating targets and libraries
+##############################
+
+Target descriptions
+===================
+
+A good starting point is to look at the init target. The source code of init is
+located at _os/src/init/_. In this directory, you will find a target description
+file named _target.mk_. This file contains the building instructions and it is
+usually very simple. The build process is controlled by defining the following
+variables.
+
+
+Build variables to be defined by you
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:'TARGET': is the name of the binary to be created. This is the
+  only *mandatory variable* to be defined in a _target.mk_ file.
+
+:'REQUIRES': expresses the requirements that must be satisfied in order to
+  build the target. You find more details about the underlying mechanism in
+  Section [Specializations].
+
+:'LIBS': is the list of libraries that are used by the target.
+
+:'SRC_CC': contains the list of '.cc' source files. The default search location
+  for source codes is the directory, where the _target.mk_ file resides.
+
+:'SRC_C': contains the list of '.c' source files.
+
+:'SRC_S': contains the list of assembly '.s' source files.
+
+:'SRC_BIN': contains binary data files to be linked to the target.
+
+:'INC_DIR': is the list of include search locations. Directories should
+  always be appended by using +=. Never use an assignment!
+
+:'EXT_OBJECTS': is a list of Genode-external objects or libraries. This
+  variable is mostly used for interfacing Genode with legacy software
+  components.
+
+
+Rarely used variables
+---------------------
+
+:'CC_OPT': contains additional compiler options to be used for '.c' as
+  well as for '.cc' files.
+
+:'CC_CXX_OPT': contains additional compiler options to be used for the
+  C++ compiler only.
+
+:'CC_C_OPT': contains additional compiler options to be used for the
+  C compiler only.
+
+
+Specifying search locations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When specifying search locations for header files via the 'INC_DIR' variable or
+for source files via 'vpath', relative pathnames are illegal to use. Instead,
+you can use the following variables to reference locations within the
+source-code repository, where your target lives:
+
+:'REP_DIR': is the base directory of the current source-code repository.
+  Normally, specifying locations relative to the base of the repository is
+  never used by _target.mk_ files but needed by library descriptions.
+
+:'PRG_DIR': is the directory, where your _target.mk_ file resides. This
+  variable is always to be used when specifying a relative path.
+
+
+Library descriptions
+====================
+
+In contrast to target descriptions that are scattered across the whole source
+tree, library descriptions are located at the central place _lib/mk_. Each
+library corresponds to a _<libname>.mk_ file. The base of the description file
+is the name of the library. Therefore, no 'TARGET' variable needs to be set.
+The source-code locations are expressed as '$(REP_DIR)'-relative 'vpath'
+commands.
+
+Library-description files support the following additional declarations:
+
+:'SHARED_LIB = yes': declares that the library should be built as a shared
+  object rather than a static library. The resulting object will be called
+  _<libname>.lib.so_.
+
+
+Specializations
+===============
+
+Building components for different platforms likely implicates portions of code
+that are tied to certain aspects of the target platform.  For example, a target
+platform may be characterized by
+
+* A kernel API such as L4v2, Linux, L4.sec,
+* A hardware architecture such as x86, ARM, Coldfire,
+* A certain hardware facility such as a custom device, or
+* Other properties such as software license requirements.
+
+Each of these attributes express a specialization of the build process. The
+build system provides a generic mechanism to handle such specializations.
+
+The _programmer_ of a software component knows the properties on which his
+software relies and thus, specifies these requirements in his build description
+file.
+
+The _user/customer/builder_ decides to build software for a specific platform
+and defines the platform specifics via the 'SPECS' variable per build
+directory in _etc/specs.conf_. In addition to an (optional) _etc/specs.conf_
+file within the build directory, the build system incorporates the first
+_etc/specs.conf_ file found in the repositories as configured for the
+build directory. For example, for a 'linux_x86' build directory, the
+_base-linux/etc/specs.conf_ file is used by default. The build directory's
+'specs.conf' file can still be used to extend the 'SPECS' declarations, for
+example to enable special features.
+
+Each '<specname>' in the 'SPECS' variable instructs the build system to
+
+* Include the 'make'-rules of a corresponding _base/mk/spec-<specname>.mk_
+  file. This enables the customization of the build process for each platform.
+
+* Search for _<libname>.mk_ files in the _lib/mk/<specname>/_ subdirectory.
+  This way, we can provide alternative implementations of one and the same
+  library interface for different platforms.
+
+Before a target or library gets built, the build system checks if the 'REQUIRES'
+entries of the build description file are satisfied by entries of the 'SPECS'
+variable. The compilation is executed only if each entry in the 'REQUIRES'
+variable is present in the 'SPECS' variable as supplied by the build directory
+configuration.
+
+
+Building tools to be executed on the host platform
+===================================================
+
+Sometimes, software requires custom tools that are used to generate source
+code or other ingredients for the build process, for example IDL compilers.
+Such tools won't be executed on top of Genode but on the host platform
+during the build process. Hence, they must be compiled with the tool chain
+installed on the host, not the Genode tool chain.
+
+The Genode build system accommodates the building of such host tools as a side
+effect of building a library or a target. Even though it is possible to add
+the tool compilation step to a regular build description file, it is
+recommended to introduce a dedicated pseudo library for building such tools.
+This way, the rules for building host tools are kept separate from rules that
+refer to Genode programs. By convention, the pseudo library should be named
+_<package>_host_tools_ and the host tools should be built at
+_<build-dir>/tool/<package>/_. With _<package>_, we refer to the name of the
+software package the tool belongs to, e.g., qt5 or mupdf. To build a tool
+named _<tool>_, the pseudo library contains a custom make rule like the
+following:
+
+! $(BUILD_BASE_DIR)/tool/<package>/<tool>:
+!     $(MSG_BUILD)$(notdir $@)
+!     $(VERBOSE)mkdir -p $(dir $@)
+!     $(VERBOSE)...build commands...
+
+To let the build system trigger the rule, add the custom target to the
+'HOST_TOOLS' variable:
+
+! HOST_TOOLS += $(BUILD_BASE_DIR)/tool/<package>/<tool>
+
+Once the pseudo library for building the host tools is in place, it can be
+referenced by each target or library that relies on the respective tools via
+the 'LIBS' declaration. The tool can be invoked by referring to
+'$(BUILD_BASE_DIR)/tool/<package>/tool'.
+
+For an example of using custom host tools, please refer to the mupdf package
+found within the libports repository. During the build of the mupdf library,
+two custom tools fontdump and cmapdump are invoked. The tools are built via
+the _lib/mk/mupdf_host_tools.mk_ library description file. The actual mupdf
+library (_lib/mk/mupdf.mk_) has the pseudo library 'mupdf_host_tools' listed
+in its 'LIBS' declaration and refers to the tools relative to
+'$(BUILD_BASE_DIR)'.
+
+
+Building additional custom targets accompanying library or program
+==================================================================
+
+There are cases when it is important to build additional targets
+besides standard files built for library or program. Of course there
+is no problem with writing specific make rules for commands that
+generate those target files but for them to be built a proper
+dependency must be specified. To achieve it those additional targets
+should be added to 'CUSTOM_TARGET_DEPS' variable like e.g. in
+iwl_firmware library from dde_linux repository:
+
+! CUSTOM_TARGET_DEPS += $(addprefix $(BIN_DIR)/,$(IMAGES))
+
+
+Automated integration and testing
+#################################
+
+Genode's cross-kernel portability is one of the prime features of the
+framework. However, each kernel takes a different route when it comes to
+configuring, integrating, and booting the system. Hence, for using a particular
+kernel, profound knowledge about the boot concept and the kernel-specific tools
+is required. To streamline the testing of Genode-based systems across the many
+different supported kernels, the framework comes equipped with tools that
+relieve you from these peculiarities.
+
+Run scripts
+===========
+
+Using so-called run scripts, complete Genode systems can be described in a
+concise and kernel-independent way. Once created, a run script can be used
+to integrate and test-drive a system scenario directly from the build directory.
+The best way to get acquainted with the concept is reviewing the run script
+for the 'hello_tutorial' located at _hello_tutorial/run/hello.run_.
+Let's revisit each step expressed in the _hello.run_ script:
+
+* Building the components needed for the system using the 'build' command.
+  This command instructs the build system to compile the targets listed in
+  the brace block. It has the same effect as manually invoking 'make' with
+  the specified argument from within the build directory.
+
+* Creating a new boot directory using the 'create_boot_directory' command.
+  The integration of the scenario is performed in a dedicated directory at
+  _<build-dir>/var/run/<run-script-name>/_. When the run script is finished,
+  this directory will contain all components of the final system.  In the
+  following, we will refer to this directory as run directory.
+
+* Installing the Genode 'config' file into the run directory using the
+  'install_config' command. The argument to this command will be written
+  to a file called 'config' at the run directory picked up by
+  Genode's init process.
+
+* Creating a bootable system image using the 'build_boot_image' command.
+  This command copies the specified list of files from the _<build-dir>/bin/_
+  directory to the run directory and executes the platform-specific steps
+  needed to transform the content of the run directory into a bootable
+  form. This form depends on the actual base platform and may be an ISO
+  image or a bootable ELF image.
+
+* Executing the system image using the 'run_genode_until' command. Depending
+  on the base platform, the system image will be executed using an emulator.
+  For most platforms, Qemu is the tool of choice used by default. On Linux,
+  the scenario is executed by starting 'core' directly from the run
+  directory. The 'run_genode_until' command takes a regular expression
+  as argument. If the log output of the scenario matches the specified
+  pattern, the 'run_genode_until' command returns. If specifying 'forever'
+  as argument (as done in 'hello.run'), this command will never return.
+  If a regular expression is specified, an additional argument determines
+  a timeout in seconds. If the regular expression does not match until
+  the timeout is reached, the run script will abort.
+
+Please note that the _hello.run_ script does not contain kernel-specific
+information. Therefore it can be executed from the build directory of any base
+platform by using:
+
+! make run/hello
+
+When invoking 'make' with an argument of the form 'run/*', the build system
+will look in all repositories for a run script with the specified name. The run
+script must be located in one of the repositories 'run/' subdirectories and
+have the file extension '.run'.
+
+For a more comprehensive run script, _os/run/demo.run_ serves as a good
+example. This run script describes Genode's default demo scenario. As seen in
+'demo.run', parts of init's configuration can be made dependent on the
+platform's properties expressed as spec values. For example, the PCI driver
+gets included in init's configuration only on platforms with a PCI bus. For
+appending conditional snippets to the _config_ file, there exists the 'append_if'
+command, which takes a condition as first and the snippet as second argument.
+To test for a SPEC value, the command '[have_spec <spec-value>]' is used as
+condition. Analogously to how 'append_if' appends strings, there exists
+'lappend_if' to append list items. The latter command is used to conditionally
+include binaries to the list of boot modules passed to the 'build_boot_image'
+command.
+
+
+The run mechanism explained
+===========================
+
+Under the hood, run scripts are executed by an expect interpreter. When the
+user invokes a run script via _make run/<run-script>_, the build system invokes
+the run tool at _<genode-dir>/tool/run_ with the run script as argument. The
+run tool is an expect script that has no other purpose than defining several
+commands used by run scripts, including a platform-specific script snippet
+called run environment ('env'), and finally including the actual run script.
+Whereas _tool/run_ provides the implementations of generic and largely
+platform-independent commands, the _env_ snippet included from the platform's
+respective _base-<platform>/run/env_ file contains all platform-specific
+commands. For reference, the most simplistic run environment is the one at
+_base-linux/run/env_, which implements the 'create_boot_directory',
+'install_config', 'build_boot_image', and 'run_genode_until' commands for Linux
+as base platform. For the other platforms, the run environments are far more
+elaborative and document precisely how the integration and boot concept works
+on each platform. Hence, the _base-<platform>/run/env_ files are not only
+necessary parts of Genode's tooling support but serve as resource for
+peculiarities of using each kernel.
+
+
+Using run script to implement test cases
+========================================
+
+Because run scripts are actually expect scripts, the whole arsenal of
+language features of the Tcl scripting language is available to them. This
+turns run scripts into powerful tools for the automated execution of test
+cases. A good example is the run script at _libports/run/lwip.run_, which tests
+the lwIP stack by running a simple Genode-based HTTP server on Qemu. It fetches
+and validates a HTML page from this server. The run script makes use of a
+regular expression as argument to the 'run_genode_until' command to detect the
+state when the web server becomes ready, subsequently executes the 'lynx' shell
+command to fetch the web site, and employs Tcl's support for regular
+expressions to validate the result. The run script works across base platforms
+that use Qemu as execution environment.
+
+To get the most out of the run mechanism, a basic understanding of the Tcl
+scripting language is required. Furthermore the functions provided by
+_tool/run_ and _base-<platform>/run/env_ should be studied.
+
+
+Automated testing across base platforms
+=======================================
+
+To execute one or multiple test cases on more than one base platform, there
+exists a dedicated tool at _tool/autopilot_. Its primary purpose is the
+nightly execution of test cases. The tool takes a list of platforms and of
+run scripts as arguments and executes each run script on each platform. The
+build directory for each platform is created at
+_/tmp/autopilot.<username>/<platform>_ and the output of each run script is
+written to a file called _<platform>.<run-script>.log_. On stderr, autopilot
+prints the statistics about whether or not each run script executed
+successfully on each platform. If at least one run script failed, autopilot
+returns a non-zero exit code, which makes it straight forward to include
+autopilot into an automated build-and-test environment.
+
+

doc/challenges.txt

@@ -16,24 +16,17 @@ research projects on Genode.
 Applications and library infrastructure
 #######################################
 
-:Port of the Ladybird web browser:
+:VNC server implementing Genode's framebuffer session interface:
 
-  [https://ladybird.org/ - Ladybird] is a new web browser developed
-  independently from the large browser-engine vendors. It is designed to
-  be light-weight and portable. Among the supported platforms is Qt,
-  which is available for Genode. This makes the porting of Ladybird a
-  tempting application of the Goa SDK.
-
-:Goa SDK running on Sculpt OS:
-
-  Genode's [https://github.com/genodelabs/goa - Goa SDK] is currently used
-  in Linux-based development environments, facilitating cross-compilation
-  to Genode. The goal of this project is the ability to use Goa directly on
-  Sculpt OS without the need for a Linux VM. This entails a number of
-  challenges, ranging from running the Goa tool itself by porting the expect
-  interpreter, over running the Genode tool chain, adjusting the
-  network-facing Goa commands to Genode's environment, to crafting custom
-  support for executing 'goa run' as a sandboxed Genode subsystem.
+  With 'Input' and 'Framebuffer', Genode provides two low-level interfaces
+  used by interactive applications. For example, the Nitpicker GUI server uses
+  these interfaces as a client and, in turn, exports multiple virtual
+  'Framebuffer' and 'Input' interfaces to its clients. This enables a
+  highly modular use of applications such as the nesting of GUIs. By
+  implementing the 'Framebuffer' and 'Input' interfaces with a VNC server
+  implementation, all graphical workloads of Genode would become available over
+  the network. One immediate application of this implementation is the remote
+  testing of graphical Genode applications running on a headless server.
 
 :Interfacing with the SAFE network:
 
@@ -46,6 +39,25 @@ Applications and library infrastructure
   integrated in the operating system, i.e., in the form of Genode components
   or a set of Genode VFS plugins.
 
+:Interactive sound switchbox based on Genode's Audio_out session interface:
+
+  Since version 10.05, Genode features a highly flexible configuration concept
+  that allows the arbitrary routing of session requests throughout the
+  hierarchic process structure. Even though primarily designed for expressing
+  mandatory-access control rules, the concept scales far beyond this use case.
+  For example, it can be used to run an arbitrary number of processes
+  implementing the same interface and connecting the different interface
+  implementations. One special case of this scenario is a chain of audio
+  filters with each using the 'Audio_out' session interface for both roles
+  client and server. Combined with the Nitpicker GUI server and Genode's
+  support for real-time priorities, this base techniques enable the creation of
+  flexible audio mixer / switchboard applications, which require dedicated
+  frameworks (e.g., Jack audio) on traditional operating systems. The goal of
+  this project is to create a showcase implementation demonstrating the
+  feasibility for creating high-quality audio applications on Genode.
+  Furthermore, we wish for feedback regarding the current design of our bulk
+  streaming interface when used for low-latency applications.
+
 :Graphical on-target IPC tracing tool using Qt:
 
   Analysing the interaction of components of a multi-server operating system
@@ -82,39 +94,31 @@ Applications and library infrastructure
 
 :Ports of popular software:
 
-  The [https://github.com/genodelabs/goa - Goa SDK] streamlines the process
-  of developing, porting, packaging, and publishing software for Genode,
-  and Sculpt OS in particular.
+  Genode features a ports mechanism to cleanly integrate 3rd-party software.
   Thanks to the C runtime, the flexible per-component VFS, the standard
-  C++ library, and a variety of supported 3rd-party libraries, porting
-  software to Genode is relatively straight forward.
-  A wish list of software that we'd like to have available on Genode is
-  available at
+  C++ library, and the Noux runtime (for UNIX software), porting software
+  to Genode is relatively straight forward. The
+  [https://genode.org/documentation/developer-resources/porting - porting guide]
+  explains the typical steps. A wish list of software that we'd like to
+  have available on Genode is available at
   [https://usr.sysret.de/jws/genode/porting_wishlist.html].
 
 :Native Open-Street-Maps (OSM) client:
 
-  When using Sculpt OS, we regularly need to spawn a fully fledged web browser
-  for using OSM or Google maps. The goal of this project would be a native
-  component that makes maps functionality directly available on Genode,
-  alleviating the urge to reach for a SaaS product. The work would include a
-  review of existing OSM clients regarding their feature sets and the
-  feasibility of porting them to Genode. Depending on the outcome of this
-  review, an existing application could be ported or a new component could be
-  developed, e.g., leveraging Genode's Qt support.
+  When using Sculpt OS, we regularly need to spawn a fully fledged web
+  browser in a virtual machine for using OSM or Google maps. The goal
+  of this project would be a native component that makes maps functionality
+  directly available on Genode, alleviating the urge to reach for a SaaS
+  product. The work would include a review of existing OSM clients regarding
+  their feature sets and the feasibility of porting them to Genode.
+  Depending on the outcome of this review, an existing application could
+  be ported or a new component could be developed, e.g., leveraging Genode's
+  Qt support.
 
 
 Application frameworks and runtime environments
 ###############################################
 
-:GTK:
-
-  Genode supports Qt as a native toolkit. But many popular applications
-  are built upon [https://www.gtk.org/ - GTK]. A port of GTK to Genode would
-  allow for the use of these applications on Sculpt OS without the need
-  of a Linux VM. A tangible goal for this line of work could be the port
-  of [https://mtpaint.sourceforge.net/ - mtPaint] to Sculpt OS.
-
 :OpenJDK:
 
   [https://openjdk.java.net/ - OpenJDK] is the reference implementation of the
@@ -139,6 +143,31 @@ Application frameworks and runtime environments
   removed from the trusted computing base of Android, facilitating the use of
   this mobile OS in high-assurance settings.
 
+:Go language runtime:
+
+  Go is a popular language in particular for web applications. In the past,
+  there were numerous attempts to make the Go runtime available on Genode
+  but so far, none of those undertakings have landed in the official
+  Genode source tree. To goal of this project is the hosting of
+  Go-written applications - in particular networking applications - as
+  Genode components. The topic comprises work on the tool-chain
+  and build-system integration, the porting the runtime libraries, and
+  the glue between the Go and Genode environments.
+
+:Combination of CAmkES with Genode:
+
+  [https://wiki.sel4.systems/CAmkES - CAmkES] is a component framework for
+  seL4. In contrast to Genode, which is a dynamic system, CAmkES-based systems
+  are defined at design time and remain fixed at runtime. Hence, CAmkES and
+  Genode can be seen as the opposite ends of component-based used-land
+  architectures. The goal of this project is to build a bridge between
+  both projects with the potential to cross-pollinate the respective communities.
+  Among the principal approaches are embedding of a single CAmkES
+  component as a Genode component (e.g., an individual device driver),
+  the hosting of a dynamic Genode system as a component within a
+  CAmkES system, or the hosting of a CAmkES system composition as a Genode
+  subsystem.
+
 :Runtime for the D programming language:
 
   The D systems programming language was designed to overcome many gripes that
@@ -152,6 +181,19 @@ Application frameworks and runtime environments
   programs, and interfacing D programs with other Genode components written in
   C++.
 
+:Using Haskell as systems-development language:
+
+  The goal of this project is the application of functional programming
+  i.e., Haskell, for the implementation of low-level Genode components.
+  Implementing critical functionalities in such a high-level language instead
+  of a classical systems language such as C or C++ would pave the way towards
+  analyzing such components with formal methods.
+
+  The use of Haskell for systems development was pioneered by the
+  [https://programatica.cs.pdx.edu/House/ - House Project]. A more recent
+  development is [https://halvm.org - HalVM] - a light-weight OS runtime for
+  Xen that is based on Haskell.
+
 :Xlib compatibility:
 
   Developments like Wayland notwithstanding, most application software on
@@ -172,44 +214,45 @@ Application frameworks and runtime environments
   requests issued by a block-session client to a block-device driver,
   such a bump-in-the-wire component could visualize
   the access patterns of a block device. Similar ideas could be pursued for
-  other session interfaces, like record/play (sound visualization) or NIC
+  other session interfaces, like the audio-out (sound visualization) or NIC
   session (live visualization of network communication).
 
   The visualization of system behavior would offer valuable insights,
   e.g., new opportunities for optimization. But more importantly, they
-  would be fun to play with.
-
-
-Platforms
-#########
-
-:Support for additional ARM SoCs:
-
-  Genode's ARM support has been focused on NXP's i.MX family, Allwinner A64
-  (used by the PinePhone), and to a lesser degree the Raspberry Pi. To make
-  Genode compatible with a larger variety of devices, the support for further
-  chip families calls for exploration. For example,
-  [https://en.wikipedia.org/wiki/Rockchip - Rockchip] SoCs are getting
-  popular in products by open-source hardware vendors such as
-  [https://pine64.com/ - Pine64] and [https://mntre.com/ - MNT].
-  The first steps have been [https://github.com/mickenx/genode-rockchip - already taken]
-  by [https://genodians.org/mickenx/index - Michael Grunditz]!
-  Another example is the Mediatek SoC family, which is popular in
-  affordable consumer smartphones.
-  Another example is the Mediatek SoC family, which is popular in
-  affordable consumer smartphones.
-
-  The process of bringing an OS like Genode to a new SoC is full of technical
-  challenges and labor-intensive, yet extremely gratifying.
-  As a guide through this process, the
-  [https://genode.org/documentation/genode-platforms-23-05.pdf - Genode Platforms]
-  book breaks the challenge down to a sequence of manageable steps, where
-  each step can be celebrated as a success.
+  would be extremely fun to play with.
 
 
 Virtualization
 ##############
 
+:VirtualBox on top of KVM on Linux:
+
+  Genode's version of VirtualBox replaces the original in-kernel VirtualBox
+  hypervisor by the virtualization mechanism of the NOVA hypervisor or the
+  Muen separation kernel. Those mechanisms look very similar the KVM
+  interface of the Linux kernel. It should in principle be possible to
+  re-target Genode's version of VirtualBox to KVM. This way, VirtualBox and
+  Qemu/KVM-based virtual machines could co-exist on the same system, which
+  is normally not possible. Also, complex Genode scenarios (like Turmvilla)
+  could be prototyped on GNU/Linux.
+
+:Xen as kernel for Genode:
+
+  Using Xen as kernel for Genode would clear the way to remove the
+  overly complex Linux OS from the trusted computing base of Xen
+  guests OSes.
+
+  Xen is a hypervisor that can host multiple virtual machines on one physical
+  machine. For driving physical devices and for virtual-machine management, Xen
+  relies on a privileged guest OS called Dom0. Currently, Linux is the
+  predominant choice to be used as Dom0, which implicates a trusted computing
+  base of millions of lines of code for the other guest OSes.
+
+  Even though Xen was designed as hypervisor, a thorough analysis done by Julian
+  Stecklina concludes that Xen qualifies well as a kernel for Genode. For
+  example, Julian implemented a version of Genode's IPC framework that utilizes
+  Xen's communication mechanisms (event channels and shared memory).
+
 :Genode as virtualization layer for Qubes OS:
 
   [https://www.qubes-os.org/ - Qubes OS] is a desktop operating system
@@ -235,37 +278,121 @@ Virtualization
   the project bears the opportunity to explore the provisioning of the
   KVM interface based on Genode's VFS plugin concept.
 
+:Hardware-accelerated graphics for virtual machines:
 
-System management and tools
-###########################
+  In
+  [https://genode.org/documentation/release-notes/17.08#Hardware-accelerated_graphics_for_Intel_Gen-8_GPUs - Genode 17.08],
+  we introduced a GPU multiplexer for Intel Broadwell along with support
+  for Mesa-based 3D-accelerated applications.
+  While designing Genode's GPU-session interface, we also aimed at supporting
+  the hardware-accelerated graphics for Genode's virtual machine monitors like
+  VirtualBox or Seoul, but until now, we did not took the practical steps of
+  implementing a virtual GPU device model.
 
-:Virtual network-boot infrastructure as Sculpt component:
+  The goal of this project is the offering of a virtual GPU to a Linux guest
+  OS running on top of Genode's existing virtualization and driver
+  infrastructure.
 
-  Network-based development work flows for PCs require a variety of tools and
-  network-configuration peculiarities. Think of a development network with a
-  custom configured DHCP server, a TFTP or HTTP server on the development
-  machine, the provisioning of a PXE boot loader, tooling for obtaining serial
-  output over AMT, or tooling for remote power control via AMT.
 
-  The goal of this project would be the hosting of all those functions in a
-  Sculpt OS component "devnet" that is exclusively in charge of a dedicated
-  LAN port of the developer's Sculpt machine. By connecting a test machine to
-  this LAN port, the test machine becomes immediately available as development
-  target without any manual installation or configuration steps needed. The
-  devnet component would interface with the rest of the Sculpt system as a
-  client of a file-system session (containing the boot payloads) and a
-  terminal session (for the virtual serial connection).
+Device drivers
+##############
 
-:Statistical profiler using Sculpt's GDB monitor:
+:Sound on the Raspberry Pi:
 
-  Starting with version 24.04, Sculpt OS provides the ability to supervise
-  selected components
-  [https://genodians.org/chelmuth/2024-05-17-on-target-debugging - using the GDB protocol].
-  The underlying mechanism and infrastructure could be leveraged for
-  implementing a statistical profiler that monitors components live.
-  Using the on-target information obtained via Sculpt's "download debug info"
-  option, the tool could display a sorted list of the most executed
-  functions, facilitating interactive on-target analysis and experimentation.
+  The goal of this project is a component that uses the Raspberry Pi's
+  PWM device to implement Genode's audio-out-session interface. Since
+  Genode's version of libSDL already supports this interface as audio
+  backend, the new driver will make the sound of all SDL-based games
+  available on the Raspberry Pi.
+
+:Data Plane Development Kit (DPDK):
+
+  Genode utilizes the network device drivers of the iPXE project, which
+  perform reasonably well for everyday use cases but are obviously not
+  designated for high-performance networking.
+  The [https://dpdk.org/ - DPDK] is a vendor-supported suite of network device
+  drivers that is specifically developed for high-performance applications.
+  It presents an attractive alternative to iPXE-based drivers. This project
+  has the goal to make DPDK drivers available as a Genode component.
+
+
+Platforms
+#########
+
+:Microkernelizing Linux:
+
+  Thanks to Genode's generic interfaces for I/O access as provided by core, all
+  Genode device drivers including drivers ported from Linux and gPXE can be
+  executed as user-level components on all supported microkernels. However, so
+  far, we have not enabled the use of these device drivers on Linux as base
+  platform. The goal of this project is the systematic replacement of in-kernel
+  Linux device drivers by Genode processes running in user space, effectively
+  reducing the Linux kernel to a runtime for Genode's core process. But moving
+  drivers to Genode processes is just the beginning. By employing further
+  Genode functionality such as its native GUI, lwIP, and Noux, many protocol
+  stacks can effectively be removed from the Linux kernel.
+
+  In 2018, Johannes Kliemann pursued this topic to a state where Genode
+  could be used as init process atop a customized Linux kernel.
+  [https://lists.genode.org/pipermail/users/2018-May/006066.html - His work]
+  included the execution of Genode's regular device drivers for VESA and
+  PS/2 as regular Genode components so that Genode's interactive demo
+  scenario ran happily on a laptop. At this time, however, only parts of
+  his results were merged into Genode's mainline.
+
+  The goal of this project is to follow up on Johannes' work, bring the
+  [https://github.com/genodelabs/genode/pull/2829 - remaining parts] into
+  shape for the inclusion into Genode, and address outstanding topics, in
+  particular the handling of DMA by user-level device drivers. Further down
+  the road, it would be tempting to explore the use of
+  [https://en.wikipedia.org/wiki/Seccomp - seccomp] as sandboxing mechanism
+  for Genode on Linux and the improvement of the Linux-specific implementation
+  of Genode's object-capability model.
+
+:Support for the HelenOS/SPARTAN kernel:
+
+  [http://www.helenos.org - HelenOS] is a microkernel-based multi-server OS
+  developed at the university of Prague. It is based on the SPARTAN microkernel,
+  which runs on a wide variety of CPU architectures including Sparc, MIPS, and
+  PowerPC. This broad platform support makes SPARTAN an interesting kernel to
+  look at alone. But a further motivation is the fact that SPARTAN does not
+  follow the classical L4 road, providing a kernel API that comes with an own
+  terminology and different kernel primitives. This makes the mapping of
+  SPARTAN's kernel API to Genode a challenging endeavour and would provide us
+  with feedback regarding the universality of Genode's internal interfaces.
+  Finally, this project has the potential to ignite a further collaboration
+  between the HelenOS and Genode communities.
+
+:Support for the XNU kernel (Darwin):
+
+  XNU is the kernel used by Darwin and Mac OS X. It is derived from the
+  MACH microkernel and extended with a UNIX-like syscall API. Because the
+  kernel is used for Mac OS X, it could represent an industry-strength
+  base platform for Genode supporting all CPU features as used by Mac OS X.
+
+:Genode on the Librem5 phone hardware:
+
+  Even though there exists a great variety of ARM-based SoCs, Genode
+  primarily focuses on the NXP i.MX family because it is - in contrast
+  to most SoCs in the consumer space - very liberal in terms of
+  good-quality public documentation and reference code, and it scales
+  from industrial to end-user-facing use cases (multi-media).
+
+  The [https://puri.sm/products/librem-5/ - Librem5] project - with its
+  mission to build a trustworthy mobile phone - has chosen the i.MX family as
+  the basis for their product for likely the same reasons that attract us.
+
+  To goal of this work is bringing Genode to the Librem5 hardware.
+  For the Librem5 project, Genode could pave the ground towards new use cases
+  like high-security markets where a regular Linux-based OS would not be
+  accepted. For the Genode community, the Librem5 hardware could become an
+  attractive mobile platform for everyday use, similar to how we developers
+  use our Genode-based [https://genode.org/download/sculpt - Sculpt OS] on our
+  laptops.
+
+
+System management
+#################
 
 :Remote management of Sculpt OS via Puppet:
 
@@ -279,3 +406,18 @@ System management and tools
   The project would explore the application of the Puppet approach and tools
   to Sculpt OS.
 
+
+Optimizations
+#############
+
+:De-privileging the VESA graphics driver:
+
+  The VESA graphics driver executes the graphics initialization code provided
+  by the graphics card via an x86 emulator. To initialize a graphics mode, this
+  code needs to access device hardware. Currently, we permit access to all
+  device registers requested by the graphics-card's code. These devices include
+  the system timer, the PCI configuration registers, and the interrupt
+  controller, which are critical for the proper operating of the kernel. The
+  goal of this work is to restrict the permissions of the VESA driver to a
+  minimum by virtualizing all devices but the actual graphics card.
+

doc/coding_style.txt

@@ -0,0 +1,299 @@
+Coding style guidelines for Genode
+##################################
+
+Things to avoid
+===============
+
+Please avoid using pre-processor macros. C++ provides language
+features for almost any case, for which a C programmer uses
+macros.
+
+:Defining constants:
+
+  Use 'enum' instead of '#define'
+  ! enum { MAX_COLORS = 3 };
+  ! enum {
+  !   COLOR_RED   = 1,
+  !   COLOR_BLUE  = 2,
+  !   COLOR_GREEN = 3
+  ! };
+
+:Meta programming:
+
+  Use templates instead of pre-processor macros. In contrast to macros,
+  templates are type-safe and fit well with the implementation syntax.
+
+:Conditional-code inclusion:
+
+  Please avoid C-hacker style '#ifdef CONFIG_PLATFROM' - '#endif'
+  constructs. Instead, factor-out the encapsulated code into a
+  separate file and introduce a proper function interface.
+  The build process should then be used to select the appropriate
+  platform-specific files at compile time. Keep platform dependent
+  code as small as possible. Never pollute existing generic code
+  with platform-specific code.
+
+
+Header of each file
+===================
+
+! /*
+!  * \brief  Short description of the file
+!  * \author Original author
+!  * \date   Creation date
+!  *
+!  * Some more detailed description. This is optional.
+!  */
+
+
+Identifiers
+===========
+
+* The first character of class names are uppercase, any other characters are
+  lowercase.
+* Function and variable names are lower case.
+* 'Multi_word_identifiers' use underline to separate words.
+* 'CONSTANTS' and template arguments are upper case.
+* Private and protected members of a class begin with an '_'-character.
+* Accessor methods are named after their corresponding attributes:
+
+  ! /**
+  !  * Request private member variable
+  !  */
+  ! int value() const { return _value; }
+  !
+  ! /**
+  !  * Set the private member variable
+  !  */
+  ! void value(int value) { _value = value; }
+
+* Accessors that return a boolean value do not carry an 'is_' prefix. E.g.,
+  a method for requesting the validity of an object should be named
+  'valid()', not 'is_valid()'.
+
+
+Indentation
+===========
+
+* Use one tab per indentation step. *Do not mix tabs and spaces!*
+* Use no tabs except at the beginning of a line.
+* Use spaces for the alignment of continuation lines such as function
+  arguments that span multiple lines. The alignment spaces of such lines
+  should start after the (tab-indented) indentation level. For example:
+  ! {
+  ! <tab>function_with_many_arguments(arg1,
+  ! <tab><--- spaces for aligment --->arg2,
+  !      ...
+  ! }
+* Remove trailing spaces at the end of lines
+
+This way, each developer can set his preferred tab size in his editor
+and the source code always looks good.
+
+_Hint:_ In VIM, use the 'set list' and 'set listchars' commands to make tabs
+and spaces visible.
+
+* If class initializers span multiple lines, put the colon on a separate
+  line and indent the initializers using one tab. For example:
+  ! Complicated_machinery(Material &material, Deadline deadline)
+  ! :
+  ! <tab>_material(material),
+  ! <tab>_deadline(deadline),
+  ! <tab>...
+  ! {
+  !      ...
+  ! }
+
+* Preferably place statements that alter the control flow - such as
+  'break', 'continue', or 'return' - at the beginning of a separate line,
+  followed by vertical space (a blank line or the closing brace of the
+  surrounding scope).
+  ! if (early_return_possible)
+  !     return;
+
+
+Switch statements
+~~~~~~~~~~~~~~~~~
+
+Switch-statement blocks should be indented as follows:
+
+! switch (color) {
+!
+! case BLUE:
+! <tab>break;
+!
+! case GREEN:
+! <tab>{
+! <tab><tab>int declaration_required;
+! <tab><tab>...
+! <tab>}
+!
+! default:
+! }
+
+Please note that the case labels have the same indentation
+level as the switch statement. This avoids a two-level
+indentation-change at the end of the switch block that
+would occur otherwise.
+
+
+Vertical whitespaces
+====================
+
+In header files:
+
+* Leave two empty lines between classes.
+* Leave one empty line between member functions.
+
+In implementation files:
+
+* Leave two empty lines between functions.
+
+
+Braces
+======
+
+* Braces after class, struct and function names are placed at a new line:
+  ! class Foo
+  ! {
+  !   public:
+  !
+  !     void method(void)
+  !     {
+  !       ...
+  !     }
+  ! };
+
+  except for one-line functions.
+
+* All other occurrences of open braces (for 'if', 'while', 'do', 'for',
+  'namespace', 'enum' etc.) are at the end of a line:
+
+  ! if (flag) {
+  !   ..
+  ! } else {
+  !   ..
+  ! }
+
+* One-line functions should be written on a single line as long as the line
+  length does not exceed approximately 80 characters.
+  Typically, this applies for accessor functions.
+  If slightly more space than one line is needed, indent as follows:
+
+  ! int heavy_computation(int a, int lot, int of, int args) {
+  !   return a + lot + of + args; }
+
+
+Comments
+========
+
+Function/method header
+~~~~~~~~~~~~~~~~~~~~~~
+
+Each public or protected (but no private) method in a header-file should be
+prepended by a header as follows:
+
+! /**
+!  * Short description
+!  *
+!  * \param a    meaning of parameter a
+!  * \param b    meaning of parameter b
+!  * \param c,d  meaning of parameters c and d
+!  *
+!  * \throw Exception_type  meaning of the exception
+!  *
+!  * \return meaning of return value
+!  *
+!  * More detailed information about the function. This is optional.
+!  */
+
+Descriptions of parameters and return values should be lower-case and brief.
+More elaborative descriptions can be documented in the text area below.
+
+In implementation files, only local and private functions should feature
+function headers.
+
+
+Single-line comments
+~~~~~~~~~~~~~~~~~~~~
+
+! /* use this syntax for single line comments */
+
+A single-line comment should be prepended by an empty line.
+Single-line comments should be short - no complete sentences. Use lower-case.
+
+C++-style comments ('//') should only be used for temporarily commenting-out
+code.  Such commented-out garbage is easy to 'grep' and there are handy
+'vim'-macros available for creating and removing such comments.
+
+
+Variable descriptions
+~~~~~~~~~~~~~~~~~~~~~
+
+Use the same syntax as for single-line comments. Insert two or more
+spaces before your comment starts.
+
+! int size;   /* in kilobytes */
+
+
+Multi-line comments
+~~~~~~~~~~~~~~~~~~~
+
+Multi-line comments are more detailed descriptions in the form of
+sentences.
+A multi-line comment should be enclosed by empty lines.
+
+! /*
+!  * This is some tricky
+!  * algorithm that works
+!  * as follows:
+!  * ...
+!  */
+
+The first and last line of a multi-line comment contain no words.
+
+
+Source-code blocks
+~~~~~~~~~~~~~~~~~~
+
+For structuring your source code, you can entitle the different
+parts of a file like this:
+
+! <- two empty lines
+!
+! /********************
+!  ** Event handlers **
+!  ********************/
+! <- one empty line
+
+Note the two stars at the left and right. There are two of them to
+make the visible width of the border match its height (typically,
+characters are ca. twice as high as wide).
+
+A source-code block header represents a headline for the following
+code. To couple this headline with the following code closer than
+with previous code, leave two empty lines above and one empty line
+below the source-code block header.
+
+
+Order of public, protected, and private blocks
+==============================================
+
+For consistency reasons, use the following class layout:
+
+! class Sandstein
+! {
+!   private:
+!     ...
+!   protected:
+!     ...
+!   public:
+! };
+
+Typically, the private section contains member variables that are used
+by public accessor functions below. In this common case, we only reference
+symbols that are defined above as it is done when programming plain C.
+
+Leave one empty line (or a line that contains only a brace) above and below
+a 'private', 'protected', or 'public' label. This also applies when the
+label is followed by a source-code block header.

doc/components.txt

@@ -34,11 +34,10 @@ of them is briefly characterized as follows:
   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.
+  'audio_out_session', 'log_session', 'nic_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 can accommodate only one client at a time.
 
 :Resource multiplexers: provide mechanisms to multiplex device resources
   to multiple clients. A typical resource multiplexer requests one
@@ -65,7 +64,7 @@ of them is briefly characterized as follows:
 Device drivers
 ##############
 
-Device drivers usually reside in the _src/driver/_ subdirectory of source-code
+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
@@ -79,23 +78,18 @@ a different SoC family such as NXP's i.MX, Allwinner, Xilinx Zynq, or RISC-V.
 Platform devices
 ================
 
-:_os/src/driver/platform/_: Platform drivers for various platforms.
+:_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/driver/acpi/_:
+:_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.
@@ -114,10 +108,10 @@ UART devices
 
 The UART device drivers implement the UART-session interface.
 
-:_os/src/driver/uart/spec/pbxa9/_:
+:_os/src/drivers/uart/spec/pbxa9/_:
   Driver for the PL011 UART as found on many ARM-based platforms.
 
-:_os/src/driver/uart/spec/x86/_:
+:_os/src/drivers/uart/spec/x86/_:
   Driver for the i8250 UART as found on PC hardware.
 
 
@@ -127,11 +121,11 @@ Framebuffer and input drivers
 Framebuffer and input drivers are implemented as clients of the
 capture-session and event-session interfaces respectively.
 
-:_os/src/driver/ps2/x86/_:
+:_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/driver/ps2/pl050/_:
+:_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
@@ -139,36 +133,33 @@ capture-session and event-session interfaces respectively.
   is made available to the driver via the SPECS machinery of the Genode build
   system.
 
-:_libports/src/driver/framebuffer/vesa/_:
+:_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/driver/framebuffer/boot/_:
+:_libports/src/drivers/framebuffer/boot/_:
   Driver for boot-time initialized framebuffers (e.g., UEFI GOP)
   discovered from the 'platform_info' ROM
 
-:_os/src/driver/framebuffer/pl11x/_:
+:_os/src/drivers/framebuffer/pl11x/_:
   Driver for the PL110/PL111 LCD display.
 
-:_os/src/driver/framebuffer/sdl/_:
+:_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/driver/framebuffer/virtio/_:
-  Driver for the Virtio virtual graphics device as supported by Qemu.
+:_os/src/drivers/gpu/intel/_:
+  An experimental Intel Graphics GPU multiplexer for Broadwell and newer.
 
-:_os/src/driver/gpu/intel/_:
-  An Intel Graphics GPU multiplexer for Broadwell and newer.
-
-:_pc/src/driver/framebuffer/intel/_:
+:_pc/src/drivers/framebuffer/intel/_:
   Framebuffer driver for Intel i915 compatible graphic cards based on
   the Linux Intel KMS driver.
 
-:_pc/src/driver/usb_host/_:
+:_pc/src/drivers/usb_host/_:
   USB host-controller driver that provides an USB session interface to
   USB drivers.
 
-:_dde_linux/src/driver/usb_hid/_:
+:_dde_linux/src/drivers/usb_hid/_:
   USB Human Interface Device driver using the USB session interface.
 
 
@@ -195,14 +186,14 @@ provided by the kernel, or a pseudo time source (busy):
 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.
+Audio drivers implement the Audio_out session interface defined at
+_os/include/audio_out_session/_ for playback and optionally the audio_in
+interface for recording.
 
-:_os/src/driver/audio/spec/linux/_:
+:_os/src/drivers/audio/spec/linux/_:
   Uses ALSA as back-end on the Linux base platform and supports only playback.
 
-:_dde_bsd/src/driver/audio/_:
+:_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.
@@ -214,17 +205,21 @@ Block drivers
 All block drivers implement the block-session interface defined at
 _os/include/block_session/_.
 
-:_os/src/driver/sd_card/pl180/_:
+:_os/src/drivers/sd_card/pl180/_:
   Driver for SD-cards connected via the PL180 device as found on the PBX-A9
   platform.
 
-:_os/src/driver/ahci/_:
+:_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/driver/nvme/_:
+:_os/src/drivers/nvme/_:
   Driver for NVMe block devices on x86 PCs.
 
-:_os/src/driver/usb_block/_:
+:_os/src/drivers/usb_block/_:
   USB Mass Storage Bulk-Only driver using the USB session interface and provides
   a block-session interface.
 
@@ -235,29 +230,28 @@ Network interface drivers
 All network interface drivers implement the NIC session interface
 defined at _os/include/nic_session/_.
 
-:_os/src/driver/nic/spec/linux/_:
+:_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/driver/nic/lan9118/_:
+:_os/src/drivers/nic/lan9118/_:
   Native device driver for the LAN9118 network adaptor as featured on the
   PBX-A9 platform.
 
-:_dde_ipxe/src/driver/nic/_:
+:_dde_ipxe/src/drivers/nic/_:
   Device drivers ported from the iPXE project. Supported devices are Intel
   E1000 and pcnet32.
 
-:_pc/src/driver/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/driver/wifi/_:
+:_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/driver/usb_net/_:
+:_dde_linux/src/drivers/usb_net/_:
   USB network driver using the USB session interface.
 
+:_dde_linux/src/drivers/nic/fec/_:
+  Driver for ethernet NICs of the i.MX SoC family.
+
 
 Resource multiplexers
 #####################
@@ -274,9 +268,9 @@ subdirectory of a source repository.
   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.
+:Audio output: The audio mixer located at _os/src/server/mixer/_ enables
+  multiple clients to use the audio-out interface. The mixing is done by simply
+  adding and clamping the signals of all present 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
@@ -288,9 +282,6 @@ subdirectory of a source repository.
   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
@@ -500,8 +491,8 @@ Libraries
   Library for implementing pseudo-graphical applications (i.e., VIM) that
   run on a text terminal.
 
-:_libports/qt6/_:
-  Qt6 application framework.
+:_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
@@ -539,14 +530,14 @@ located in their respective directory.
 :_demo/src/app/scout/_:
   Graphical hypertext browser used for Genode's default demonstration scenario.
 
-:_os/src/monitor/_:
-  Variant of init that allows for the debugging of components via GDB over a
-  remote connection.
+:_ports/src/app/gdb_monitor/_:
+  Application that allows the debugging of a process via GDB over a remote
+  connection.
 
-:_libports/src/app/qt6/qt_launchpad/_:
+:_libports/src/app/qt5/qt_launchpad/_:
   Graphical application starter implemented using Qt.
 
-:_libports/src/app/qt6/examples/_:
+:_libports/src/app/qt5/examples/_:
   Several example applications that come with Qt.
 
 :_os/src/app/sequence/_:
@@ -586,9 +577,6 @@ Package-management components
 :_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.

doc/conventions.txt

@@ -1,333 +1,70 @@
 
+      Conventions for the Genode development
+
 
-              ==================================================
-              Conventions and coding-style guidelines for Genode
-              ==================================================
+                  Norman Feske
 
 
-
-Documentation and naming of files
-#################################
+Documentation
+#############
 
 We use the GOSH syntax [https://github.com/nfeske/gosh] for documentation and
 README files.
 
-We encourage that each directory contains a file called 'README' that briefly
-explains what the directory is about.
 
-File names
-----------
+README files
+############
 
-All normal file names are lowercase. Filenames should be chosen to be
-expressive. Someone who explores your files for the first time might not
+Each directory should contain a file called 'README' that briefly explains
+what the directory is about. In 'doc/Makefile' is a rule for
+generating a directory overview from the 'README' files automatically.
+
+You can structure your 'README' file by using the GOSH style for subsections:
+! Subsection
+! ~~~~~~~~~~
+Do not use chapters or sections in your 'README' files.
+
+
+Filenames
+#########
+
+All normal filenames are lowercase.  Filenames should be chosen to be
+expressive.  Someone who explores your files for the first time might not
 understand what 'mbi.cc' means but 'multiboot_info.cc' would ring a bell. If a
-file name contains multiple words, use the '_' to separate them (instead of
+filename contains multiple words, use the '_' to separate them (instead of
 'miscmath.h', use 'misc_math.h').
 
 
 Coding style
 ############
 
-Things to avoid
-===============
+A common coding style helps a lot to ease collaboration. The official coding
+style of the Genode base components is described in 'doc/coding_style.txt'.
+If you consider working closely together with the Genode main developers,
+your adherence to this style is greatly appreciated.
 
-Please avoid using pre-processor macros. C++ provides language
-features for almost any case, for which a C programmer uses
-macros.
 
-:Defining constants:
+Include files and RPC interfaces
+################################
 
-  Use 'enum' instead of '#define'
-  ! enum { MAX_COLORS = 3 };
-  ! enum {
-  !   COLOR_RED   = 1,
-  !   COLOR_BLUE  = 2,
-  !   COLOR_GREEN = 3
-  ! };
+Never place include files directly into the '<repository>/include/' directory
+but use a meaningful subdirectory that corresponds to the component that
+provides the interfaces.
 
-:Meta programming:
+Each RPC interface is represented by a separate include subdirectory. For
+an example, see 'base/include/ram_session/'. The header file that defines
+the RPC function interface has the same base name as the directory. The RPC
+stubs are called 'client.h' and 'server.h'. If your interface uses a custom
+capability type, it is defined in 'capability.h'. Furthermore, if your
+interface is a session interface of a service, it is good practice to
+provide a connection class in a 'connection.h' file for managing session-
+construction arguments and the creation and destruction of sessions.
 
-  Use templates instead of pre-processor macros. In contrast to macros,
-  templates are type-safe and fit well with the implementation syntax.
+Specialization-dependent include directories are placed in 'include/<specname>/'.
 
-:Conditional-code inclusion:
 
-  Please avoid C-hacker style '#ifdef CONFIG_PLATFROM' - '#endif'
-  constructs. Instead, factor-out the encapsulated code into a
-  separate file and introduce a proper function interface.
-  The build process should then be used to select the appropriate
-  platform-specific files at compile time. Keep platform dependent
-  code as small as possible. Never pollute existing generic code
-  with platform-specific code.
-
-
-Header of each file
-===================
-
-! /*
-!  * \brief  Short description of the file
-!  * \author Original author
-!  * \date   Creation date
-!  *
-!  * Some more detailed description. This is optional.
-!  */
-
-
-Identifiers
-===========
-
-* The first character of class names are uppercase, any other characters are
-  lowercase.
-* Function and variable names are lower case.
-* 'Multi_word_identifiers' use underline to separate words.
-* 'CONSTANTS' and template arguments are upper case.
-* Private and protected members of a class begin with an '_'-character.
-* Accessor methods are named after their corresponding attributes:
-
-  ! /**
-  !  * Request private member variable
-  !  */
-  ! int value() const { return _value; }
-  !
-  ! /**
-  !  * Set the private member variable
-  !  */
-  ! void value(int value) { _value = value; }
-
-* Accessors that return a boolean value do not carry an 'is_' prefix. E.g.,
-  a method for requesting the validity of an object should be named
-  'valid()', not 'is_valid()'.
-
-
-Indentation
-===========
-
-* Use one tab per indentation step. *Do not mix tabs and spaces!*
-* Use no tabs except at the beginning of a line.
-* Use spaces for the alignment of continuation lines such as function
-  arguments that span multiple lines. The alignment spaces of such lines
-  should start after the (tab-indented) indentation level. For example:
-  ! {
-  ! <tab>function_with_many_arguments(arg1,
-  ! <tab><--- spaces for aligment --->arg2,
-  !      ...
-  ! }
-* Remove trailing spaces at the end of lines
-
-This way, each developer can set his preferred tab size in his editor
-and the source code always looks good.
-
-_Hint:_ In VIM, use the 'set list' and 'set listchars' commands to make tabs
-and spaces visible.
-
-* If class initializers span multiple lines, put the colon on a separate
-  line and indent the initializers using one tab. For example:
-  ! Complicated_machinery(Material &material, Deadline deadline)
-  ! :
-  ! <tab>_material(material),
-  ! <tab>_deadline(deadline),
-  ! <tab>...
-  ! {
-  !      ...
-  ! }
-
-* Preferably place statements that alter the control flow - such as
-  'break', 'continue', or 'return' - at the beginning of a separate line,
-  followed by vertical space (a blank line or the closing brace of the
-  surrounding scope).
-  ! if (early_return_possible)
-  !     return;
-
-
-Switch statements
-~~~~~~~~~~~~~~~~~
-
-Switch-statement blocks should be indented as follows:
-
-! switch (color) {
-!
-! case BLUE:
-! <tab>break;
-!
-! case GREEN:
-! <tab>{
-! <tab><tab>int declaration_required;
-! <tab><tab>...
-! <tab>}
-!
-! default:
-! }
-
-Please note that the case labels have the same indentation
-level as the switch statement. This avoids a two-level
-indentation-change at the end of the switch block that
-would occur otherwise.
-
-
-Vertical whitespaces
-====================
-
-In header files:
-
-* Leave two empty lines between classes.
-* Leave one empty line between member functions.
-
-In implementation files:
-
-* Leave two empty lines between functions.
-
-
-Braces
-======
-
-* Braces after class, struct and function names are placed at a new line:
-  ! class Foo
-  ! {
-  !   public:
-  !
-  !     void method(void)
-  !     {
-  !       ...
-  !     }
-  ! };
-
-  except for one-line functions.
-
-* All other occurrences of open braces (for 'if', 'while', 'do', 'for',
-  'namespace', 'enum' etc.) are at the end of a line:
-
-  ! if (flag) {
-  !   ..
-  ! } else {
-  !   ..
-  ! }
-
-* One-line functions should be written on a single line as long as the line
-  length does not exceed approximately 80 characters.
-  Typically, this applies for accessor functions.
-  If slightly more space than one line is needed, indent as follows:
-
-  ! int heavy_computation(int a, int lot, int of, int args) {
-  !   return a + lot + of + args; }
-
-
-Comments
-========
-
-Function/method header
-~~~~~~~~~~~~~~~~~~~~~~
-
-Each public or protected (but no private) method in a header-file should be
-prepended by a header as follows:
-
-! /**
-!  * Short description
-!  *
-!  * \param a    meaning of parameter a
-!  * \param b    meaning of parameter b
-!  * \param c,d  meaning of parameters c and d
-!  *
-!  * \throw Exception_type  meaning of the exception
-!  *
-!  * \return meaning of return value
-!  *
-!  * More detailed information about the function. This is optional.
-!  */
-
-Descriptions of parameters and return values should be lower-case and brief.
-More elaborative descriptions can be documented in the text area below.
-
-In implementation files, only local and private functions should feature
-function headers.
-
-
-Single-line comments
-~~~~~~~~~~~~~~~~~~~~
-
-! /* use this syntax for single line comments */
-
-A single-line comment should be prepended by an empty line.
-Single-line comments should be short - no complete sentences. Use lower-case.
-
-C++-style comments ('//') should only be used for temporarily commenting-out
-code.  Such commented-out garbage is easy to 'grep' and there are handy
-'vim'-macros available for creating and removing such comments.
-
-
-Variable descriptions
-~~~~~~~~~~~~~~~~~~~~~
-
-Use the same syntax as for single-line comments. Insert two or more
-spaces before your comment starts.
-
-! int size;   /* in kilobytes */
-
-
-Multi-line comments
-~~~~~~~~~~~~~~~~~~~
-
-Multi-line comments are more detailed descriptions in the form of
-sentences.
-A multi-line comment should be enclosed by empty lines.
-
-! /*
-!  * This is some tricky
-!  * algorithm that works
-!  * as follows:
-!  * ...
-!  */
-
-The first and last line of a multi-line comment contain no words.
-
-
-Source-code blocks
-~~~~~~~~~~~~~~~~~~
-
-For structuring your source code, you can entitle the different
-parts of a file like this:
-
-! <- two empty lines
-!
-! /********************
-!  ** Event handlers **
-!  ********************/
-! <- one empty line
-
-Note the two stars at the left and right. There are two of them to
-make the visible width of the border match its height (typically,
-characters are ca. twice as high as wide).
-
-A source-code block header represents a headline for the following
-code. To couple this headline with the following code closer than
-with previous code, leave two empty lines above and one empty line
-below the source-code block header.
-
-
-Order of public, protected, and private blocks
-==============================================
-
-For consistency reasons, use the following class layout:
-
-! class Sandstein
-! {
-!   private:
-!     ...
-!   protected:
-!     ...
-!   public:
-! };
-
-Typically, the private section contains member variables that are used
-by public accessor functions below. In this common case, we only reference
-symbols that are defined above as it is done when programming plain C.
-
-Leave one empty line (or a line that contains only a brace) above and below
-a 'private', 'protected', or 'public' label. This also applies when the
-label is followed by a source-code block header.
-
-
-Naming of Genode services
-=========================
+Service Names
+#############
 
 Service names as announced via the 'parent()->announce()' function follow
 the following convention:

doc/depot.txt

@@ -0,0 +1,514 @@
+
+
+                        ============================
+                        Package management on Genode
+                        ============================
+
+
+                               Norman Feske
+
+
+
+Motivation and inspiration
+##########################
+
+The established system-integration work flow with Genode is based on
+the 'run' tool, which automates the building, configuration, integration,
+and testing of Genode-based systems. Whereas the run tool succeeds in
+overcoming the challenges that come with Genode's diversity of kernels and
+supported hardware platforms, its scalability is somewhat limited to
+appliance-like system scenarios: The result of the integration process is
+a system image with a certain feature set. Whenever requirements change,
+the system image is replaced with a new created image that takes those
+requirements into account. In practice, there are two limitations of this
+system-integration approach:
+
+First, since the run tool implicitly builds all components required for a
+system scenario, the system integrator has to compile all components from
+source. E.g., if a system includes a component based on Qt5, one needs to
+compile the entire Qt5 application framework, which induces significant
+overhead to the actual system-integration tasks of composing and configuring
+components.
+
+Second, general-purpose systems tend to become too complex and diverse to be
+treated as system images. When looking at commodity OSes, each installation
+differs with respect to the installed set of applications, user preferences,
+used device drivers and system preferences. A system based on the run tool's
+work flow would require the user to customize the run script of the system for
+each tweak. To stay up to date, the user would need to re-create the
+system image from time to time while manually maintaining any customizations.
+In practice, this is a burden, very few end users are willing to endure.
+
+The primary goal of Genode's package management is to overcome these
+scalability limitations, in particular:
+
+* Alleviating the need to build everything that goes into system scenarios
+  from scratch,
+* Facilitating modular system compositions while abstracting from technical
+  details,
+* On-target system update and system development,
+* Assuring the user that system updates are safe to apply by providing the
+  ability to easily roll back the system or parts thereof to previous versions,
+* Securing the integrity of the deployed software,
+* Fostering a federalistic evolution of Genode systems,
+* Low friction for existing developers.
+
+The design of Genode's package-management concept is largely influenced by Git
+as well as the [https://nixos.org/nix/ - Nix] package manager. In particular
+the latter opened our eyes to discover the potential that lies beyond the
+package management employed in state-of-the art commodity systems. Even though
+we considered adapting Nix for Genode and actually conducted intensive
+experiments in this direction (thanks to Emery Hemingway who pushed forward
+this line of work), we settled on a custom solution that leverages Genode's
+holistic view on all levels of the operating system including the build system
+and tooling, source structure, ABI design, framework API, system
+configuration, inter-component interaction, and the components itself. Whereby
+Nix is designed for being used on top of Linux, Genode's whole-systems view
+led us to simplifications that eliminated the needs for Nix' powerful features
+like its custom description language.
+
+
+Nomenclature
+############
+
+When speaking about "package management", one has to clarify what a "package"
+in the context of an operating system represents. Traditionally, a package
+is the unit of delivery of a bunch of "dumb" files, usually wrapped up in
+a compressed archive. A package may depend on the presence of other
+packages. Thereby, a dependency graph is formed. To express how packages fit
+with each other, a package is usually accompanied with meta data
+(description). Depending on the package manager, package descriptions follow
+certain formalisms (e.g., package-description language) and express
+more-or-less complex concepts such as versioning schemes or the distinction
+between hard and soft dependencies.
+
+Genode's package management does not follow this notion of a "package".
+Instead of subsuming all deliverable content under one term, we distinguish
+different kinds of content, each in a tailored and simple form. To avoid the
+clash of the notions of the common meaning of a "package", we speak of
+"archives" as the basic unit of delivery. The following subsections introduce
+the different categories.
+Archives are named with their version as suffix, appended via a slash. The
+suffix is maintained by the author of the archive. The recommended naming
+scheme is the use of the release date as version suffix, e.g.,
+'report_rom/2017-05-14'.
+
+
+Raw-data archives
+=================
+
+A raw-data archive contains arbitrary data that is - in contrast to executable
+binaries - independent from the processor architecture. Examples are
+configuration data, game assets, images, or fonts. The content of raw-data
+archives is expected to be consumed by components at runtime. It is not
+relevant for the build process for executable binaries. Each raw-data
+archive contains merely a collection of data files. There is no meta data.
+
+
+API archive
+===========
+
+An API archive has the structure of a Genode source-code repository. It may
+contain all the typical content of such a source-code repository such as header
+files (in the _include/_ subdirectory), source codes (in the _src/_
+subdirectory), library-description files (in the _lib/mk/_ subdirectory), or
+ABI symbols (_lib/symbols/_ subdirectory). At the top level, a LICENSE file is
+expected that clarifies the license of the contained source code. There is no
+meta data contained in an API archive.
+
+An API archive is meant to provide _ingredients_ for building components. The
+canonical example is the public programming interface of a library (header
+files) and the library's binary interface in the form of an ABI-symbols file.
+One API archive may contain the interfaces of multiple libraries. For example,
+the interfaces of libc and libm may be contained in a single "libc" API
+archive because they are closely related to each other. Conversely, an API
+archive may contain a single header file only. The granularity of those
+archives may vary. But they have in common that they are used at build time
+only, not at runtime.
+
+
+Source archive
+==============
+
+Like an API archive, a source archive has the structure of a Genode
+source-tree repository and is expected to contain all the typical content of
+such a source repository along with a LICENSE file. But unlike an API archive,
+it contains descriptions of actual build targets in the form of Genode's usual
+'target.mk' files.
+
+In addition to the source code, a source archive contains a file
+called 'used_apis', which contains a list of API-archive names with each
+name on a separate line. For example, the 'used_apis' file of the 'report_rom'
+source archive looks as follows:
+
+! base/2017-05-14
+! os/2017-05-13
+! report_session/2017-05-13
+
+The 'used_apis' file declares the APIs needed to incorporate into the build
+process when building the source archive. Hence, they represent _build-time_
+_dependencies_ on the specific API versions.
+
+A source archive may be equipped with a top-level file called 'api' containing
+the name of exactly one API archive. If present, it declares that the source
+archive _implements_ the specified API. For example, the 'libc/2017-05-14'
+source archive contains the actual source code of the libc and libm as well as
+an 'api' file with the content 'libc/2017-04-13'. The latter refers to the API
+implemented by this version of the libc source package (note the differing
+versions of the API and source archives)
+
+
+Binary archive
+==============
+
+A binary archive contains the build result of the equally-named source archive
+when built for a particular architecture. That is, all files that would appear
+at the _<build-dir>/bin/_ subdirectory when building all targets present in
+the source archive. There is no meta data present in a binary archive.
+
+A binary archive is created out of the content of its corresponding source
+archive and all API archives listed in the source archive's 'used_apis' file.
+Note that since a binary archive depends on only one source archive, which
+has no further dependencies, all binary archives can be built independently
+from each other.
+For example, a libc-using application needs the source code of the
+application as well as the libc's API archive (the libc's header file and
+ABI) but it does not need the actual libc library to be present.
+
+
+Package archive
+===============
+
+A package archive contains an 'archives' file with a list of archive names
+that belong together at runtime. Each listed archive appears on a separate line.
+For example, the 'archives' file of the package archive for the window
+manager 'wm/2018-02-26' looks as follows:
+
+! genodelabs/raw/wm/2018-02-14
+! genodelabs/src/wm/2018-02-26
+! genodelabs/src/report_rom/2018-02-26
+! genodelabs/src/decorator/2018-02-26
+! genodelabs/src/floating_window_layouter/2018-02-26
+
+In contrast to the list of 'used_apis' of a source archive, the content of
+the 'archives' file denotes the origin of the respective archives
+("genodelabs"), the archive type, followed by the versioned name of the
+archive.
+
+An 'archives' file may specify raw archives, source archives, or package
+archives (as type 'pkg'). It thereby allows the expression of _runtime
+dependencies_. If a package archive lists another package archive, it inherits
+the content of the listed archive. This way, a new package archive may easily
+customize an existing package archive.
+
+A package archive does not specify binary archives directly as they differ
+between the architecture and are already referenced by the source archives.
+
+In addition to an 'archives' file, a package archive is expected to contain
+a 'README' file explaining the purpose of the collection.
+
+
+Depot structure
+###############
+
+Archives are stored within a directory tree called _depot/_. The depot
+is structured as follows:
+
+! <user>/pubkey
+! <user>/download
+! <user>/src/<name>/<version>/
+! <user>/api/<name>/<version>/
+! <user>/raw/<name>/<version>/
+! <user>/pkg/<name>/<version>/
+! <user>/bin/<arch>/<src-name>/<src-version>/
+
+The <user> stands for the origin of the contained archives. For example, the
+official archives provided by Genode Labs reside in a _genodelabs/_
+subdirectory. Within this directory, there is a 'pubkey' file with the
+user's public key that is used to verify the integrity of archives downloaded
+from the user. The file 'download' specifies the download location as an URL.
+
+Subsuming archives in a subdirectory that correspond to their the origin
+(user) serves two purposes. First, it provides a user-local name space for
+versioning archives. E.g., there might be two versions of a
+'nitpicker/2017-04-15' source archive, one by "genodelabs" and one by
+"nfeske". However, since each version resides under its origin's subdirectory,
+version-naming conflicts between different origins cannot happen. Second, by
+allowing multiple archive origins in the depot side-by-side, package archives
+may incorporate archives of different origins, which fosters the goal of a
+federalistic development, where contributions of different origins can be
+easily combined.
+
+The actual archives are stored in the subdirectories named after the archive
+types ('raw', 'api', 'src', 'bin', 'pkg'). Archives contained in the _bin/_
+subdirectories are further subdivided in the various architectures (like
+'x86_64', or 'arm_v7').
+
+
+Depot management
+################
+
+The tools for managing the depot content reside under the _tool/depot/_
+directory. When invoked without arguments, each tool prints a brief
+description of the tool and its arguments.
+
+Unless stated otherwise, the tools are able to consume any number of archives
+as arguments. By default, they perform their work sequentially. This can be
+changed by the '-j<N>' argument, where <N> denotes the desired level of
+parallelization. For example, by specifying '-j4' to the _tool/depot/build_
+tool, four concurrent jobs are executed during the creation of binary archives.
+
+
+Downloading archives
+====================
+
+The depot can be populated with archives in two ways, either by creating
+the content from locally available source codes as explained by Section
+[Automated extraction of archives from the source tree], or by downloading
+ready-to-use archives from a web server.
+
+In order to download archives originating from a specific user, the depot's
+corresponding user subdirectory must contain two files:
+
+:_pubkey_: contains the public key of the GPG key pair used by the creator
+  (aka "user") of the to-be-downloaded archives for signing the archives. The
+  file contains the ASCII-armored version of the public key.
+
+:_download_: contains the base URL of the web server where to fetch archives
+  from. The web server is expected to mirror the structure of the depot.
+  That is, the base URL is followed by a sub directory for the user,
+  which contains the archive-type-specific subdirectories.
+
+If both the public key and the download locations are defined, the download
+tool can be used as follows:
+
+! ./tool/depot/download genodelabs/src/zlib/2018-01-10
+
+The tool automatically downloads the specified archives and their
+dependencies. For example, as the zlib depends on the libc API, the libc API
+archive is downloaded as well. All archive types are accepted as arguments
+including binary and package archives. Furthermore, it is possible to download
+all binary archives referenced by a package archive. For example, the
+following command downloads the window-manager (wm) package archive including
+all binary archives for the 32-bit x86 architecture. Downloaded binary
+archives are always accompanied with their corresponding source and used API
+archives.
+
+! ./tool/depot/download genodelabs/pkg/x86_64/wm/2018-02-26
+
+Archive content is not downloaded directly to the depot. Instead, the
+individual archives and signature files are downloaded to a quarantine area in
+the form of a _public/_ directory located in the root of Genode's source tree.
+As its name suggests, the _public/_ directory contains data that is imported
+from or to-be exported to the public. The download tool populates it with the
+downloaded archives in their compressed form accompanied with their
+signatures.
+
+The compressed archives are not extracted before their signature is checked
+against the public key defined at _depot/<user>/pubkey_. If however the
+signature is valid, the archive content is imported to the target destination
+within the depot. This procedure ensures that depot content - whenever
+downloaded - is blessed by a cryptographic signature of its creator.
+
+
+Building binary archives from source archives
+=============================================
+
+With the depot populated with source and API archives, one can use the
+_tool/depot/build_ tool to produce binary archives. The arguments have the
+form '<user>/bin/<arch>/<src-name>' where '<arch>' stands for the targeted
+CPU architecture. For example, the following command builds the 'zlib'
+library for the 64-bit x86 architecture. It executes four concurrent jobs
+during the build process.
+
+! ./tool/depot/build genodelabs/bin/x86_64/zlib/2018-01-10 -j4
+
+Note that the command expects a specific version of the source archive as
+argument. The depot may contain several versions. So the user has to decide,
+which one to build.
+
+After the tool is finished, the freshly built binary archive can be found in
+the depot within the _genodelabs/bin/<arch>/<src>/<version>/_ subdirectory.
+Only the final result of the built process is preserved. In the example above,
+that would be the _zlib.lib.so_ library.
+
+For debugging purposes, it might be interesting to inspect the intermediate
+state of the build. This is possible by adding 'KEEP_BUILD_DIR=1' as argument
+to the build command. The binary's intermediate build directory can be
+found besides the binary archive's location named with a '.build' suffix.
+
+By default, the build tool won't attempt to rebuild a binary archive that is
+already present in the depot. However, it is possible to force a rebuild via
+the 'REBUILD=1' argument.
+
+
+Publishing archives
+===================
+
+Archives located in the depot can be conveniently made available to the public
+using the _tool/depot/publish_ tool. Given an archive path, the tool takes
+care of determining all archives that are implicitly needed by the specified
+one, wrapping the archive's content into compressed tar archives, and signing
+those.
+
+As a precondition, the tool requires you to possess the private key that
+matches the _depot/<you>/pubkey_ file within your depot. The key pair should
+be present in the key ring of your GNU privacy guard.
+
+To publish archives, one needs to specify the specific version to publish.
+For example:
+
+! ./tool/depot/publish <you>/pkg/x86_64/wm/2018-02-26
+
+The command checks that the specified archive and all dependencies are present
+in the depot. It then proceeds with the archiving and signing operations. For
+the latter, the pass phrase for your private key will be requested. The
+publish tool prints the information about the processed archives, e.g.:
+
+! publish /.../public/<you>/api/base/2018-02-26.tar.xz
+! publish /.../public/<you>/api/framebuffer_session/2017-05-31.tar.xz
+! publish /.../public/<you>/api/gems/2018-01-28.tar.xz
+! publish /.../public/<you>/api/input_session/2018-01-05.tar.xz
+! publish /.../public/<you>/api/nitpicker_gfx/2018-01-05.tar.xz
+! publish /.../public/<you>/api/nitpicker_session/2018-01-05.tar.xz
+! publish /.../public/<you>/api/os/2018-02-13.tar.xz
+! publish /.../public/<you>/api/report_session/2018-01-05.tar.xz
+! publish /.../public/<you>/api/scout_gfx/2018-01-05.tar.xz
+! publish /.../public/<you>/bin/x86_64/decorator/2018-02-26.tar.xz
+! publish /.../public/<you>/bin/x86_64/floating_window_layouter/2018-02-26.tar.xz
+! publish /.../public/<you>/bin/x86_64/report_rom/2018-02-26.tar.xz
+! publish /.../public/<you>/bin/x86_64/wm/2018-02-26.tar.xz
+! publish /.../public/<you>/pkg/wm/2018-02-26.tar.xz
+! publish /.../public/<you>/raw/wm/2018-02-14.tar.xz
+! publish /.../public/<you>/src/decorator/2018-02-26.tar.xz
+! publish /.../public/<you>/src/floating_window_layouter/2018-02-26.tar.xz
+! publish /.../public/<you>/src/report_rom/2018-02-26.tar.xz
+! publish /.../public/<you>/src/wm/2018-02-26.tar.xz
+
+
+According to the output, the tool populates a directory called _public/_
+at the root of the Genode source tree with the to-be-published archives.
+The content of the _public/_ directory is now ready to be copied to a
+web server, e.g., by using rsync.
+
+
+Automated extraction of archives from the source tree
+#####################################################
+
+Genode users are expected to populate their local depot with content obtained
+via the _tool/depot/download_ tool. However, Genode developers need a way to
+create depot archives locally in order to make them available to users. Thanks
+to the _tool/depot/extract_ tool, the assembly of archives does not need to be
+a manual process. Instead, archives can be conveniently generated out of the
+source codes present in the Genode source tree and the _contrib/_ directory.
+
+However, the granularity of splitting source code into archives, the
+definition of what a particular API entails, and the relationship between
+archives must be augmented by the archive creator as this kind of information
+is not present in the source tree as is. This is where so-called "archive
+recipes" enter the picture. An archive recipe defines the content of an
+archive. Such recipes can be located at an _recipes/_ subdirectory of any
+source-code repository, similar to how port descriptions and run scripts
+are organized. Each _recipe/_ directory contains subdirectories for the
+archive types, which, in turn, contain a directory for each archive. The
+latter is called a _recipe directory_.
+
+Recipe directory
+----------------
+
+The recipe directory is named after the archive _omitting the archive version_
+and contains at least one file named _hash_. This file defines the version
+of the archive along with a hash value of the archive's content
+separated by a space character. By tying the version name to a particular hash
+value, the _extract_ tool is able to detect the appropriate points in time
+whenever the version should be increased due to a change of the archive's
+content.
+
+API, source, and raw-data archive recipes
+-----------------------------------------
+
+Recipe directories for API, source, or raw-data archives contain a
+_content.mk_ file that defines the archive content in the form of make
+rules. The content.mk file is executed from the archive's location within
+the depot. Hence, the contained rules can refer to archive-relative files as targets.
+The first (default) rule of the content.mk file is executed with a customized
+make environment:
+
+:GENODE_DIR: A variable that holds the path to root of the Genode source tree,
+:REP_DIR: A variable with the path to source code repository where the recipe
+  is located
+:port_dir: A make function that returns the directory of a port within the
+  _contrib/_ directory. The function expects the location of the
+  corresponding port file as argument, for example, the 'zlib' recipe
+  residing in the _libports/_ repository may specify '$(REP_DIR)/ports/zlib'
+  to access the 3rd-party zlib source code.
+
+Source archive recipes contain simplified versions of the 'used_apis' and
+(for libraries) 'api' files as found in the archives. In contrast to the
+depot's counterparts of these files, which contain version-suffixed names,
+the files contained in recipe directories omit the version suffix. This
+is possible because the extract tool always extracts the _current_ version
+of a given archive from the source tree. This current version is already
+defined in the corresponding recipe directory.
+
+Package-archive recipes
+-----------------------
+
+The recipe directory for a package archive contains the verbatim content of
+the to-be-created package archive except for the _archives_ file. All other
+files are copied verbatim to the archive. The content of the recipe's
+_archives_ file may omit the version information from the listed ingredients.
+Furthermore, the user part of each entry can be left blank by using '_' as a
+wildcard. When generating the package archive from the recipe, the extract
+tool will replace this wildcard with the user that creates the archive.
+
+
+Convenience front-end to the extract, build tools
+#################################################
+
+For developers, the work flow of interacting with the depot is most often the
+combination of the _extract_ and _build_ tools whereas the latter expects
+concrete version names as arguments. The _create_ tool accelerates this common
+usage pattern by allowing the user to omit the version names. Operations
+implicitly refer to the _current_ version of the archives as defined in
+the recipes.
+
+Furthermore, the _create_ tool is able to manage version updates for the
+developer. If invoked with the argument 'UPDATE_VERSIONS=1', it automatically
+updates hash files of the involved recipes by taking the current date as
+version name. This is a valuable assistance in situations where a commonly
+used API changes. In this case, the versions of the API and all dependent
+archives must be increased, which would be a labour-intensive task otherwise.
+If the depot already contains an archive of the current version, the create
+tools won't re-create the depot archive by default. Local modifications of
+the source code in the repository do not automatically result in a new archive.
+To ensure that the depot archive is current, one can specify 'FORCE=1' to
+the create tool. With this argument, existing depot archives are replaced by
+freshly extracted ones and version updates are detected. When specified for
+creating binary archives, 'FORCE=1' normally implies 'REBUILD=1'. To prevent
+the superfluous rebuild of binary archives whose source versions remain
+unchanged, 'FORCE=1' can be combined with the argument 'REBUILD='.
+
+
+Accessing depot content from run scripts
+########################################
+
+The depot tools are not meant to replace the run tool but rather to complement
+it. When both tools are combined, the run tool implicitly refers to "current"
+archive versions as defined for the archive's corresponding recipes. This way,
+the regular run-tool work flow can be maintained while attaining a
+productivity boost by fetching content from the depot instead of building it.
+
+Run scripts can use the 'import_from_depot' function to incorporate archive
+content from the depot into a scenario. The function must be called after the
+'create_boot_directory' function and takes any number of pkg, src, or raw
+archives as arguments. An archive is specified as depot-relative path of the
+form '<user>/<type>/name'. Run scripts may call 'import_from_depot'
+repeatedly. Each argument can refer to a specific version of an archive or
+just the version-less archive name. In the latter case, the current version
+(as defined by a corresponding archive recipe in the source tree) is used.
+
+If a 'src' archive is specified, the run tool integrates the content of
+the corresponding binary archive into the scenario. The binary archives
+are selected according the spec values as defined for the build directory.
+

doc/getting_started.txt

@@ -0,0 +1,153 @@
+
+                      =============================
+                      How to start exploring Genode
+                      =============================
+
+                               Norman Feske
+
+
+Abstract
+########
+
+This guide is meant to provide you a painless start with using the Genode OS
+Framework. It explains the steps needed to get a simple demo system running
+on Linux first, followed by the instructions on how to run the same scenario
+on a microkernel.
+
+
+Quick start to build Genode for Linux
+#####################################
+
+The best starting point for exploring Genode is to run it on Linux. Make sure
+that your system satisfies the following requirements:
+
+* GNU Make version 3.81 or newer
+* 'libSDL-dev'
+* 'tclsh' and 'expect'
+* 'byacc' (only needed for the L4/Fiasco kernel)
+* 'qemu' and 'xorriso' (for testing non-Linux platforms via Qemu)
+
+For using the entire collection of ported 3rd-party software, the following
+packages should be installed additionally: 'autoconf2.64', 'autogen', 'bison',
+'flex', 'g++', 'git', 'gperf', 'libxml2-utils', 'subversion', and 'xsltproc'.
+
+Your exploration of Genode starts with obtaining the source code of the
+[https://sourceforge.net/projects/genode/files/latest/download - latest version]
+of the framework. For detailed instructions and alternatives to the
+download from Sourceforge please refer to [https://genode.org/download].
+Furthermore, you will need to install the official Genode tool chain, which
+you can download at [https://genode.org/download/tool-chain].
+
+The Genode build system never touches the source tree but generates object
+files, libraries, and programs in a dedicated build directory. We do not have a
+build directory yet. For a quick start, let us create one for the Linux base
+platform:
+
+! cd <genode-dir>
+! ./tool/create_builddir x86_64
+
+This creates a new build directory for building x86_64 binaries in './build'.
+The build system creates unified binaries that work on the given
+architecture independent from the underlying base platform, in this case Linux.
+
+Now change into the fresh build directory:
+
+! cd build/x86_64
+
+Please uncomment the following line in 'etc/build.conf' to make the
+build process as smooth as possible.
+
+! RUN_OPT += --depot-auto-update
+
+To give Genode a try, build and execute a simple demo scenario via:
+
+! make KERNEL=linux BOARD=linux run/demo
+
+By invoking 'make' with the 'run/demo' argument, all components needed by the
+demo scenario are built and the demo is executed. This includes all components
+which are implicitly needed by the base platform. The base platform that the
+components will be executed upon on is selected via the 'KERNEL' and 'BOARD'
+variables. If you are interested in looking behind the scenes of the demo
+scenario, please refer to 'doc/build_system.txt' and the run script at
+'os/run/demo.run'.
+
+
+Using platforms other than Linux
+================================
+
+Running Genode on Linux is the most convenient way to get acquainted with the
+framework. However, the point where Genode starts to shine is when used as the
+user land executed on a microkernel. The framework supports a variety of
+different kernels such as L4/Fiasco, L4ka::Pistachio, OKL4, and NOVA. Those
+kernels largely differ in terms of feature sets, build systems, tools, and boot
+concepts. To relieve you from dealing with those peculiarities, Genode provides
+you with an unified way of using them. For each kernel platform, there exists
+a dedicated description file that enables the 'prepare_port' tool to fetch and
+prepare the designated 3rd-party sources. Just issue the following command
+within the toplevel directory of the Genode source tree:
+
+! ./tool/ports/prepare_port <platform>
+
+Note that each 'base-<platform>' directory comes with a 'README' file, which
+you should revisit first when exploring the base platform. Additionally, most
+'base-<platform>' directories provide more in-depth information within their
+respective 'doc/' subdirectories.
+
+For the VESA driver on x86, the x86emu library is required and can be
+downloaded and prepared by again invoking the 3rd-party sources preparation
+tool:
+
+! ./tool/ports/prepare_port x86emu
+
+On x86 base platforms the GRUB2 boot loader is required and can be
+downloaded and prepared by invoking:
+
+! ./tool/ports/prepare_port grub2
+
+Now that the base platform is prepared, the 'create_builddir' tool can be used
+to create a build directory for your architecture of choice by giving the
+architecture as argument. To see the list of available architecture, execute
+'create_builddir' with no arguments. Note, that not all kernels support all
+architectures.
+
+For example, to give the demo scenario a spin on the OKL4 kernel, the following
+steps are required:
+
+# Download the kernel:
+  ! cd <genode-dir>
+  ! ./tool/ports/prepare_port okl4
+# Create a build directory
+  ! ./tool/create_builddir x86_32
+# Uncomment the following line in 'x86_32/etc/build.conf'
+  ! REPOSITORIES += $(GENODE_DIR)/repos/libports
+# Build and execute the demo using Qemu
+  ! make -C build/x86_32 KERNEL=okl4 BOARD=pc run/demo
+
+The procedure works analogously for the other base platforms. You can, however,
+reuse the already created build directory and skip its creation step if the
+architecture matches.
+
+
+How to proceed with exploring Genode
+####################################
+
+Now that you have taken the first steps into using Genode, you may seek to
+get more in-depth knowledge and practical experience. The foundation for doing
+so is a basic understanding of the build system. The documentation at
+'build_system.txt' provides you with the information about the layout of the
+source tree, how new components are integrated, and how complete system
+scenarios can be expressed. Equipped with this knowledge, it is time to get
+hands-on experience with creating custom Genode components. A good start is the
+'hello_tutorial', which shows you how to implement a simple client-server
+scenario. To compose complex scenarios out of many small components, the
+documentation of the Genode's configuration concept at 'os/doc/init.txt' is an
+essential reference.
+
+Certainly, you will have further questions on your way with exploring Genode.
+The best place to get these questions answered is the Genode mailing list.
+Please feel welcome to ask your questions and to join the discussions:
+
+:Genode Mailing Lists:
+
+  [https://genode.org/community/mailing-lists]
+

doc/gsoc_2012.txt

@@ -0,0 +1,236 @@
+
+
+                          ==========================
+                          Google Summer of Code 2012
+                          ==========================
+
+
+Genode Labs has applied as mentoring organization for the Google Summer of Code
+program in 2012. This document summarizes all information important to Genode's
+participation in the program.
+
+:[http://www.google-melange.com/gsoc/homepage/google/gsoc2012]:
+  Visit the official homepage of the Google Summer of Code program.
+
+*Update* Genode Labs was not accepted as mentoring organization for GSoC 2012.
+
+
+Application of Genode Labs as mentoring organization
+####################################################
+
+:Organization ID: genodelabs
+
+:Organization name: Genode Labs
+
+:Organization description:
+
+  Genode Labs is a self-funded company founded by the original creators of the
+  Genode OS project. Its primary mission is to bring the Genode operating-system
+  technology, which started off as an academic research project, to the real
+  world. At present, Genode Labs is the driving force behind the Genode OS
+  project.
+
+:Organization home page url:
+
+  http://www.genode-labs.com
+
+:Main organization license:
+
+  GNU General Public License version 2
+
+:Admins:
+
+  nfeske, chelmuth
+
+:What is the URL for your Ideas page?:
+
+  [http://genode.org/community/gsoc_2012]
+
+:What is the main IRC channel for your organization?:
+
+  #genode
+
+:What is the main development mailing list for your organization?:
+
+  genode-main@lists.sourceforge.net
+
+:Why is your organization applying to participate? What do you hope to gain?:
+
+  During the past three months, our project underwent the transition from a
+  formerly company-internal development to a completely open and transparent
+  endeavour. By inviting a broad community for participation in shaping the
+  project, we hope to advance Genode to become a broadly used and recognised
+  technology. GSoC would help us to build our community.
+
+  The project has its roots at the University of Technology Dresden where the
+  Genode founders were former members of the academic research staff. We have
+  a long and successful track record with regard to supervising students. GSoC
+  would provide us with the opportunity to establish and cultivate
+  relationships to new students and to spawn excitement about Genode OS
+  technology.
+
+:Does your organization have an application templateo?:
+
+  GSoC student projects follow the same procedure as regular community
+  contributions, in particular the student is expected to sign the Genode
+  Contributor's Agreement. (see [http://genode.org/community/contributions])
+
+:What criteria did you use to select your mentors?:
+
+  We selected the mentors on the basis of their long-time involvement with the
+  project and their time-tested communication skills. For each proposed working
+  topic, there is least one stakeholder with profound technical background within
+  Genode Labs. This person will be the primary contact person for the student
+  working on the topic. However, we will encourgage the student to make his/her
+  development transparant to all community members (i.e., via GitHub). So
+  So any community member interested in the topic is able to bring in his/her
+  ideas at any stage of development. Consequently, in practive, there will be
+  multiple persons mentoring each students.
+
+:What is your plan for dealing with disappearing students?:
+
+  Actively contact them using all channels of communication available to us,
+  find out the reason for disappearance, trying to resolve the problems. (if
+  they are related to GSoC or our project for that matter).
+
+:What is your plan for dealing with disappearing mentors?:
+
+  All designated mentors are local to Genode Labs. So the chance for them to
+  disappear to very low. However, if a mentor disappears for any serious reason
+  (i.e., serious illness), our organization will provide a back-up mentor.
+
+:What steps will you take to encourage students to interact with your community?:
+
+  First, we discussed GSoC on our mailing list where we received an overly
+  positive response. We checked back with other Open-Source projects related to
+  our topics, exchanged ideas, and tried to find synergies between our
+  respective projects. For most project ideas, we have created issues in our
+  issue tracker to collect technical information and discuss the topic.
+  For several topics, we already observed interests of students to participate.
+
+  During the work on the topics, the mentors will try to encourage the
+  students to play an active role in discussions on our mailing list, also on
+  topics that are not strictly related to the student project. We regard an
+  active participation as key to to enable new community members to develop a
+  holistic view onto our project and gather a profound understanding of our
+  methodologies.
+
+  Student projects will be carried out in a transparent fashion at GitHub.
+  This makes it easy for each community member to get involved, discuss
+  the rationale behind design decisions, and audit solutions.
+
+
+Topics
+######
+
+While discussing GSoC participation on our mailing list, we identified the
+following topics as being well suited for GSoC projects. However, if none of
+those topics receives resonance from students, there is more comprehensive list
+of topics available at our road map and our collection of future challenges:
+
+:[http://genode.org/about/road-map]:   Road-map
+:[http://genode.org/about/challenges]: Challenges
+
+
+Combining Genode with the HelenOS/SPARTAN kernel
+================================================
+
+[http://www.helenos.org - HelenOS] is a microkernel-based multi-server OS
+developed at the university of Prague. It is based on the SPARTAN microkernel,
+which runs on a wide variety of CPU architectures including Sparc, MIPS, and
+PowerPC. This broad platform support makes SPARTAN an interesting kernel to
+look at alone. But a further motivation is the fact that SPARTAN does not
+follow the classical L4 road, providing a kernel API that comes with an own
+terminology and different kernel primitives. This makes the mapping of
+SPARTAN's kernel API to Genode a challenging endeavour and would provide us
+with feedback regarding the universality of Genode's internal interfaces.
+Finally, this project has the potential to ignite a further collaboration
+between the HelenOS and Genode communities.
+
+
+Block-level encryption
+======================
+
+Protecting privacy is one of the strongest motivational factors for developing
+Genode. One pivotal element with that respect is the persistence of information
+via block-level encryption. For example, to use Genode every day at Genode
+Labs, it's crucial to protect the confidentiality of some information that's
+not part of the Genode code base, e.g., emails and reports. There are several
+expansion stages imaginable to reach the goal and the basic building blocks
+(block-device interface, ATA/SATA driver for Qemu) are already in place.
+
+:[https://github.com/genodelabs/genode/issues/55 - Discuss the issue...]:
+
+
+Virtual NAT
+===========
+
+For sharing one physical network interface among multiple applications, Genode
+comes with a component called nic_bridge, which implements proxy ARP. Through
+this component, each application receives a distinct (virtual) network
+interface that is visible to the real network. I.e., each application requests
+an IP address via a DHCP request at the local network. An alternative approach
+would be a component that implements NAT on Genode's NIC session interface.
+This way, the whole Genode system would use only one IP address visible to the
+local network. (by stacking multiple nat and nic_bridge components together, we
+could even form complex virtual networks inside a single Genode system)
+
+The implementation of the virtual NAT could follow the lines of the existing
+nic_bridge component. For parsing network packets, there are already some handy
+utilities available (at os/include/net/).
+
+:[https://github.com/genodelabs/genode/issues/114 - Discuss the issue...]:
+
+
+Runtime for the Go or D programming language
+============================================
+
+Genode is implemented in C++. However, we are repeatedly receiving requests
+for offering more safe alternatives for implementing OS-level functionality
+such as device drivers, file systems, and other protocol stacks. The goals
+for this project are to investigate the Go and D programming languages with
+respect to their use within Genode, port the runtime of of those languages
+to Genode, and provide a useful level of integration with Genode.
+
+
+Block cache
+===========
+
+Currently, there exists only the iso9660 server that is able to cache block
+accesses. A generic solution for caching block-device accesses would be nice.
+One suggestion is a component that requests a block session (routed to a block
+device driver) as back end and also announces a block service (front end)
+itself. Such a block-cache server waits for requests at the front end and
+forwards them to the back end. But it uses its own memory to cache blocks.
+
+The first version could support only read-only block devices (such as CDROM) by
+caching the results of read accesses. In this version, we already need an
+eviction strategy that kicks in once the block cache gets saturated. For a
+start this could be FIFO or LRU (least recently used).
+
+A more sophisticated version would support write accesses, too. Here we need a
+way to sync blocks to the back end at regular intervals in order to guarantee
+that all block-write accesses are becoming persistent after a certain time. We
+would also need a way to explicitly flush the block cache (i.e., when the
+front-end block session gets closed).
+
+:[https://github.com/genodelabs/genode/issues/113 - Discuss the issue...]:
+
+
+; _Since Genode Labs was not accepted as GSoC mentoring organization, the_
+; _following section has become irrelevant. Hence, it is commented-out_
+;
+; Student applications
+; ####################
+;
+; The formal steps for applying to the GSoC program will be posted once Genode
+; Labs is accepted as mentoring organization. If you are a student interested
+; in working on a Genode-related GSoC project, now is a good time to get
+; involved with the Genode community. The best way is joining the discussions
+; at our mailing list and the issue tracker. This way, you will learn about
+; the currently relevant topics, our discussion culture, and the people behind
+; the project.
+;
+; :[http://genode.org/community/mailing-lists]: Join our mailing list
+; :[https://github.com/genodelabs/genode/issues]: Discuss issues around Genode
+

doc/news.txt

@@ -4,588 +4,6 @@
                                ===========
 
 
-Genode OS Framework release 24.11 | 2024-11-22
-##############################################
-
-| With mirrored and panoramic multi-monitor setups, pointer grabbing,
-| atomic blitting and panning, and panel-self-refresh support, Genode's GUI
-| stack gets ready for the next decade. Hardware-wise, version 24.11 brings
-| a massive driver update for the i.MX SoC family. As a special highlight, the
-| release is accompanied by the first edition of the free book "Genode
-| Applications" as a gateway for application developers into Genode.
-
-Closing up the Year of Sculpt OS usability as the theme of our road map
-for 2024, we are excited to unveil the results of two intense lines of
-usability-concerned work with the release of Genode 24.11.
-
-For the usability of the Genode-based Sculpt OS as day-to-day operating
-system, the support of multi-monitor setups has been an unmet desire
-for a long time. Genode 24.11 does not only deliver a solution as a
-singular feature but improves the entire GUI stack in a holistic way,
-addressing panel self-refresh, mechanisms needed to overcome tearing
-artifacts, rigid resource partitioning between GUI applications, up to
-pointer-grabbing support.
-
-The second line of work addresses the usability of application development for
-Genode and Sculpt OS in particular. Over the course of the year, our Goa SDK
-has seen a succession of improvements that make the development, porting,
-debugging, and publishing of software a breeze. Still, given Genode's
-novelties, the learning curve to get started has remained challenging. Our new
-book "Genode Applications" is intended as a gateway into the world of Genode
-for those of us who enjoy dwelling in architectural beauty but foremost want
-to get things done. It features introductory material, explains fundamental
-concepts and components, and invites the reader on to a ride through a series
-of beginner-friendly as well as advanced tutorials. The book can be downloaded
-for free at [https://genode.org].
-
-Regarding hardware support, our work during the release cycle was hugely
-motivated by the prospect of bringing Genode to the MNT Pocket Reform laptop,
-which is based on the NXP i.MX8MP SoC. Along this way, we upgraded all
-Linux-based i.MX drivers to kernel version 6.6 while consolidating a variety
-of vendor kernels, equipped our platform driver with watchdog support, and
-added board support for this platform to Sculpt OS.
-
-You can find these among more topics covered in the detailed
-[https:/documentation/release-notes/24.11 - release documentation of version 24.11...]
-
-
-Sculpt OS release 24.10 | 2024-10-30
-####################################
-
-| Thanks to a largely revamped GUI stack, the Genode-based
-| Sculpt OS 24.10 has gained profound support for multi-monitor setups.
-
-Among the many usability-related topics on our road map, multi-monitor
-support is certainly the most anticipated feature. It motivated a holistic
-modernization of Genode's GUI stack over several months, encompassing drivers,
-the GUI multiplexer, inter-component interfaces, up to widget toolkits. Sculpt
-OS 24.10 combines these new foundations with a convenient
-[https:/documentation/articles/sculpt-24-10#Multi-monitor_support - user interface]
-for controlling monitor modes, making brightness adjustments, and setting up
-mirrored and panoramic monitor configurations.
-
-Besides this main theme, version 24.10 benefits from the advancements of the
-Genode OS Framework over the past six months: compatibility with Qt6,
-drivers ported from the Linux kernel version 6.6.47, and comprehensive
-[https:/documentation/release-notes/24.08#Goa_SDK - debugging support]
-for the Goa SDK.
-
-Sculpt OS 24.10 is available as ready-to-use system image for PC hardware,
-the PinePhone, and the MNT Reform laptop at the
-[https:/download/sculpt - Sculpt download page] accompanied
-with updated [https:/documentation/articles/sculpt-24-10 - documentation].
-
-
-Genode OS Framework release 24.08 | 2024-08-29
-##############################################
-
-| Genode 24.08 introduces the Qt6 application framework, updates all
-| Linux-based components and PC device drivers to Linux version 6.6.47,
-| equips the Goa SDK with remote debugging support, modernizes the base
-| and GUI interfaces of the framework, extends the board support for
-| i.MX-based devices, and explores AVX on x86.
-
-The highlights of Genode 24.08 are the addition of the Qt6 application
-framework in addition to the time-tested Qt5 and the major update of all
-Linux-based components and PC device drivers. So Genode users can enjoy
-current-generation commodity software and drivers across all kernels supported
-by the framework.
-
-For developers, the new combination of Genode's recent advances in
-on-target debugging with the Goa SDK enables seamless remote debugging.
-
-Regarding hardware support, the new version broadens the driver landscape for
-NXP i.MX-based devices, paving the way for Sculpt OS on the
-[https://shop.mntre.com/products/mnt-pocket-reform - MNT Pocket Reform]
-open-source hardware laptop.
-
-For the full picture, please refer to the
-[https:/documentation/release-notes/24.08 - release documentation of version 24.08...]
-
-
-New community forum at Discourse | 2024-08-13
-#############################################
-
-| Our new community forum is organized by Genode users to share ideas
-| and experiences, help newcomers, and discuss Genode-related projects.
-
-The new forum complements the existing
-[http:/community/mailing-lists - mailing list] and
-[https://github.com/genodelabs/genode - issue tracker]
-with a place for casual conversation among newcomers, seasoned users,
-and developers.
-
-[https://genode.discourse.group]
-
-As the forum is a place for users, it is moderated by users. Thanks a lot
-to Spencer and Cedric for constituting the initial moderation team!
-
-
-Meet us at FroSCon during August 17-18 | 2024-07-30
-###################################################
-
-| The Genode project will host a booth at this year's Free
-| and Open-Source Software Conference in Sankt Augustin.
-
-Besides FOSDEM, public appearances of Genode are rather rare.
-All the more delighted we are about the opportunity to host
-a booth at the upcoming FrOScon conference.
-
-*FrOScon Free and Open-Source Software Conference*
-
-*August 18 and 17 in Sankt Augustin*
-
-[https://froscon.org]
-
-The Genode stand will be maintained by the Genode team members
-Stefan Kalkowski, Johannes Schlatow, Christian Helmuth, and
-Norman Feske. It goes without saying that we will have Sculpt
-OS in various forms and flavors with us to showcase. Whether
-you like to get acquainted with our project or touch base with
-us developers in person, FrOScon might present the perfect
-opportunity!
-
-
-Genode OS Framework release 24.05 | 2024-05-30
-##############################################
-
-| The highlights of Genode 24.05 are the new ability to run Sculpt OS on
-| our custom kernel, GDB on Sculpt OS, suspend/resume, the redesign of
-| the framework's USB infrastructure, and the completed transition to
-| the new audio interfaces. The release is accompanied with the annual
-| update of the "Genode Foundations" book.
-
-With Genode 24.05, the underpinnings of the many usability improvements
-of the [https://genode.org/news/sculpt-os-release-24.04 - latest] Sculpt OS
-release found their way into the framework. Among them are a completely
-redesigned USB infrastructure that allows for fine-grained and dynamic
-assignment of USB devices to components and virtual machines, the consistent
-use of the audio facilities introduced in February, and the driver life-cycle
-management for suspend/resume.
-
-Beside those usability-related topics, two mile-stone achievements stand out.
-First, we have realized our long-time vision of running Sculpt OS on our
-custom kernel specifically designed for Genode. With Intel virtualization
-support, the release delivers the final missing piece of this puzzle.
-Second, our long-hedged dream of natural on-target debugging via the GNU
-debugger running directly on Sculpt OS has become true. This feature, which
-has been in the works for more than a year, enables Sculpt OS users to
-leverage GDB for the development of applications, services, and even device
-drivers.
-
-The release is accompanied by a new version of the "Genode Foundations" book,
-which is the go-to documentation of the framework.
-Further topics of the current release range from timing and network-throughput
-optimizations, over updated 3rd-party software like Mesa, libSDL2, and cURL,
-to developer tooling. Find these among many more topics covered in the detailed
-[https:/documentation/release-notes/24.05 - release documentation of version 24.05...]
-
-
-Sculpt OS release 24.04 | 2024-04-26
-####################################
-
-| Sculpt OS 24.04 is rich of new user-visible features.
-| It now supports 4K displays and I2C touchpads out of the box,
-| brings experimental support for suspend/resume,
-| allows the fine-grained assignment of USB devices to applications and VMs,
-| and introduces new audio-mixing capabilities.
-
-The release of version 24.04 adheres to
-our [https://genode.org/about/road-map - declared] focus on Sculpt OS usability
-during this year. Seasoned users will immediately recognize the new power of the
-component-management UI, offering easy control over optional features,
-software providers, and software installation. Among many little
-user-interface improvements, the component graph and configuration interface
-have become scrollable, boosting the interactive user experience.
-
-When looking closely at the components, users will recognize a whole new set
-of drivers neatly grouped under hardware. In contrast to earlier versions,
-which operated these drivers hidden from the user, the new version manages the
-drivers dynamically and fully transparent for the user. The change makes the
-user interface more logical and simpler. However, the driving force behind this
-approach
-was our aspired support for suspend/resume, which requires the dynamic
-life-cycle management of drivers. This brings us to the technical highlight of
-the release: After on-and-off development for more than a year, we are more
-than happy offering suspend/resume as an experimental feature.
-
-As culmination of a second long-term development, version 24.04 employs a new
-and much more flexible interplay between the USB-host driver and components
-accessing USB devices. The dynamic assignment of devices to virtual machines
-and other components has become a breeze.
-
-Just in time for the release, Sculpt OS has received a completely overhauled
-audio stack that supports pluggable drivers, arbitrary sample rates, and the
-flexible routing and mixing of audio signals. We are eager to stress and
-refine the taken approach over the upcoming release cycle to make low-latency
-audio a commodity on Sculpt OS.
-
-Thanks to our routine with running Sculpt OS on modern laptops day to day,
-version 24.04 bumps the range of supported hardware. Displays up to 4K are
-supported out of the box now, and touchpads of laptops like the Gen13 Framework
-have become operational.
-
-Speaking of developers, the release offers two bold new features targeted at
-this specific demography, namely the support for on-target debugging via GDB,
-and the ability to use Sculpt OS as a remote test target of Genode's Goa SDK.
-Look out for more information about these features in the upcoming weeks
-at [https://genodians.org].
-
-Sculpt OS 24.04 is available as ready-to-use system image at the
-[https://genode.org/download/sculpt - Sculpt download page] accompanied
-with updated [https://genode.org/documentation/articles/sculpt-24-04 - documentation].
-
-
-Genode OS Framework release 24.02 | 2024-02-29
-##############################################
-
-| Version 24.02 revisits Genode's audio support for latency-sensitive
-| scenarios, flexible sample rates, and pluggable drivers. It also introduces
-| the new ability of the Goa SDK to use Sculpt OS as remote test target,
-| comes with a new TCP/IP stack based on Linux 6.1.20, makes drivers aware
-| of suspend/resume, and improves HID event handling.
-
-Genode 24.02 kicks off the year with a profound redesign of the framework's
-audio infrastructure, addressing the routing and mixing of multi-channel audio
-streams at flexible sample rates, the dynamic starting and removal of audio
-sources and sinks, and latency optimization.
-
-Besides audio, the second infrastructural rework is a new TCP/IP stack based
-on DDE-Linux 6.1.20. It wraps up our long-year transition from a fairly
-fragmented landscape of ported driver code to the consistent use of our modern
-Linux device-driver environment across all Linux-based drivers and protocol
-stacks.
-
-The feature highlight of the release is the new ability of using Sculpt OS as
-a remote test target for the Goa SDK during application development. Thanks
-to this new feature, Genode applications can be developed and tested in a
-quick and uniform way, whether testing directly on a Linux-based development
-environment, or on a Sculpt PC reachable via a local network, or a PinePhone
-connected to the same wireless access point.
-
-Further highlights of the release are the versatile handling of human-interface
-devices including the calibration of motion events, the use of Vivante GPUs by
-multiple clients, and the driver-related preparatory steps needed for
-implementing suspend/resume for Sculpt OS.
-
-You can find the changes presented in full detail in the
-[https:/documentation/release-notes/24.02 - release documentation of version 24.02...]
-
-
-Road Map for 2024 | 2024-01-18
-##############################
-
-| After intensively concentrating on deeply technical topics below the surface
-| in 2023, we are going to reap user-visible rewards in 2024 by focussing on
-| Sculpt OS usability.
-
-Thanks to the input gathered from our annual road-map discussion on Genode's
-[https://genode.org/community/mailing-lists - mailing list], we have updated
-the project [https://genode.org/about/road-map - road map] for 2024.
-
-Without hesitation, our developer community quickly rallied behind the topic
-"Sculpt OS usability", desiring to boost the user experience with respect to
-multi-monitor usage, convenient interactive UIs for common tasks,
-profound support for touchpads and touchscreens, tearing-free graphics,
-low-latency audio, casual on-target debugging, and suspend/resume.
-
-The focus on usability notwithstanding, we will steadily continue with the
-gardening of Genode's driver landscape, fostering the consistent use of drivers
-ported from up-to-date Linux kernels, clear-cut ACPI support, and making
-drivers pluggable.
-In 2024, we will also promote Genode's custom (base-hw) microkernel to become
-the default kernel for Sculpt OS, which is the culmination of a multi-year
-effort.
-
-Please find our reflection of the past year and the complete plan for 2024
-presented on Genode's official [https:/about/road-map - road-map page].
-
-
-Genode OS Framework release 23.11 | 2023-11-30
-##############################################
-
-| Genode 23.11 moves the IOMMU driver from the kernel to the user land,
-| introduces CPU power/temperature/frequency monitoring and steering,
-| comes with a new API for low-complexity GUI applications, and
-| streamlines the framework's virtualization interface. It also improves
-| developer ergonomics and showcases the port of the Linphone VoIP stack.
-
-Version 23.11 of the Genode OS Framework introduces DMA protection as
-kernel-agnostic feature, parting with the tradition of driving I/O protection
-units from the kernel. This radical move is accompanied by a sweeping
-modernization of the framework's virtualization interface across kernels and
-instruction-set architectures. In other words, the release is dominated by
-deeply technical topics.
-
-That said, it is not void of user-facing features either, as illustrated by
-the new port of the Linphone VoIP stack using the Goa tool, the extension of
-the Seoul virtual machine monitor to 64-bit guests, and the support for CPU
-power/temperature/frequency monitoring and steering on PC platforms.
-Furthermore, developers receive better tooling for the use and distribution of
-debug builds, and will observe a welcomed boost of their development-test
-cycles thanks to a largely streamlined build-system.
-
-These and more topics are covered in full detail by the
-[https:/documentation/release-notes/23.11 - release documentation of version 23.11...]
-
-
-Sculpt OS release 23.10 | 2023-10-26
-####################################
-
-| Modern PCs provide plenty of metering and power-management options.
-| Version 23.10 of the Genode-based Sculpt operating system makes these features
-| available via an interactive user interface. One can watch the temperature
-| of each CPU core, monitor the individual CPU frequencies, switch between
-| power profiles, and reveal details about power draw.
-
-Our official
-[https://genode.org/documentation/articles/sculpt-23-10 - documentation]
-introduces Sculpt as an operating system that puts the user in the position
-of full control. With the new release, this promise is taken to the precise
-control and monitoring of physical CPU parameters.
-
-Besides restricting workloads to specific CPU cores, each individual core can
-be interactively parametrized, e.g., by balancing performance against power
-efficiency. The effects of changing these parameters become immediately
-visible by the monitored frequencies, temperature, and power draw. The new
-knobs add plenty of play value and an entirely new sense of control to the
-user experience. You can find the new power-control feature described in a
-[https://genodians.org/alex-ab/2023-10-23-msr - dedicated article].
-
-The advanced power-control abilities are accompanied with generally improved
-support for modern laptops. E.g., on the Framework Gen 12 laptop,
-features like battery monitoring, keyboard backlight control, and external
-displays just work now.
-
-Like the previous release, Sculpt OS is available for both PCs and the
-PinePhone. The PinePhone version received several usability improvements
-motivated by the feedback we got from the Pine64 community. Most importantly,
-a new screensaver reduces the power draw to less than 40%, making the device
-more viable in practice.
-Under the hood, Sculpt completely removes the drivers for the display and the
-touchscreen while the screen is blanked. Those drivers are restarted when
-pressing the power button. Furthermore, the volume buttons have become
-functional, and the dial pad has become more flexible.
-
-Beside the user-visible improvements, the underpinnings of Sculpt OS
-received a number of improvements. The entire software is now consistently
-built with GCC 12.3. The former iPXE-based network driver has been replaced
-by driver code of the Linux kernel 6.1.20, which works nicely on modern
-machines. The new version also introduces the principle mechanisms needed
-for on-target debugging, switches to a much revised virtualization interface,
-and replaces the block-encryption engine of the file vault. Users of the latter
-should follow the documented
-[https://genodians.org/m-stein/2023-10-25-file-vault-migration-1 - migration steps].
-
-Sculpt OS 23.10 for PC and PinePhone is available as ready-to-use system image
-at the [https://genode.org/download/sculpt - Sculpt download page] accompanied
-with updated [https://genode.org/documentation/articles/sculpt-23-10 - documentation].
-Seasoned Sculpt users can conveniently switch to the new version via the
-system-update dialog.
-
-
-Genode OS Framework release 23.08 | 2023-08-24
-##############################################
-
-| The main theme of the current release is tooling for developing, debugging,
-| porting, and publishing Genode components. Beyond that, the release improves
-| driver support and the internals of core and the base-framework.
-
-The headline features of this release introduce a new multi-component debug
-monitor and extend the Goa tool with support for working with multiple
-projects.
-
-The new debug monitor reapproaches Genode's GDB debugging support and sets
-smooth on-target debugging in Sculpt OS as its final goal. The monitor can
-transparently replace the Init component and is equipped with support for
-multi-component debugging by GDB inferiors. The Goa tool evolves into an
-all-encompassing alternative to Genode's traditional work flows for developing,
-porting, and publishing applications. With this release, runtime testing with
-Goa gets extremely flexible and handling of multiple Goa projects becomes a no
-brainer.
-
-Beside the tooling topics, we round out the release with a new PC NIC driver
-based on Linux, new RaspberryPi/i.MX6 USB host-controller drivers,
-hardware-button and screensaver support on the PinePhone, improved Intel
-GPU/display, WiFi, and audio drivers.
-
-Find all details of changes and improvements in the
-[https:/documentation/release-notes/23.08 - release documentation of version 23.08...]
-
-
-Genode OS Framework release 23.05 | 2023-05-31
-##############################################
-
-| Besides the annual documentation update, the scheduled tool-chain update,
-| and the switch to C++20, the release puts the spotlight on the Goa tool,
-| which enables the use of existing SDKs like Lomiri or Rust's cargo for
-| targeting Genode.
-
-By now, the dedication of Genode's May releases to housekeeping tasks has
-become a fine tradition, and this year is no different. With version 23.05,
-the framework consistently switches from the C++ standard C++17 to C++20,
-thanks to our new tool chain based on GCC 12.3, which will serve us for the
-next two years. Speaking of consistency, both Genode books "Foundations" and
-"Platforms" have been updated to the most recent version of the framework. You
-can find the PDFs at the [https://genode.org - genode.org front page].
-
-Following the recent release of Sculpt OS 23.04 targeting both PC and mobile
-platforms, Genode 23.05 brings good news for application developers interested
-in targeting Genode and Sculpt OS in particular. The release introduces the
-ability to use existing SDKs, in particular the Lomiri UI toolkit as well as
-Rust's cargo for crafting Genode applications.
-
-A prominent topic among the previous releases is our Linux device-driver
-environment (DDE), which allows for the use of Linux drivers as Genode
-components. The current release continues this line of work by upgrading DDE
-to Linux 6.1.20 and by using DDE as enabler of our cross-platform Wifi stack
-that works for the PC and ARM platforms like the PinePhone. This way, Genode
-users can benefit from the enormous efforts of the Linux kernel community
-targeting modern hardware.
-
-Further highlights of the new version are the initial use of our custom
-base-hw microkernel as x86 hypervisor, a profoundly reworked block-encryption
-stack, and updates of supported 3rd-party software like the seL4 kernel and
-VirtualBox.
-
-All changes are covered in detail by the official
-[https:/documentation/release-notes/23.05 - release documentation of version 23.05...]
-
-
-Sculpt OS release 23.04 | 2023-04-28
-####################################
-
-| Sculpt OS 23.04 marks the first-time PinePhone support in addition to the PC
-| version. With this release, the system supports live upgrades of the boot
-| image, rendering Sculpt updates and the switching between versions a matter of
-| some easy steps. The new preset feature brings entire application scenarios to
-| your screen after just one click/tap.
-
-With the fresh release 23.04, the Sculpt operating system boards the PinePhone
-to explore the mobile world and, thereby, adds a second platform to its
-year-long support for Intel PCs. In preparation, we added two key features to
-Genode during the past months, which are the phone-oriented Sculpt
-user-interface variant and the system-update functionality. Now, Sculpt
-versions can be switched by three easy steps directly in the integrated user
-interface: downloading system images to the software depot, install the
-desired version on the boot medium, and reboot the device.
-
-Further, the release supports so-called presets in the system menu UI, which
-are entire runtime scenarios. The user can load and switch between presets by
-just one click. Presets currently available in Sculpt are a simple GUI demo
-(nano3d), a simple desktop including background picture and window manager,
-and a ready to use Falkon web browser. Still, components can be integrated
-into the system (or the currently running preset) by the + menu of the
-component graph.
-
-Sculpt OS 23.04 for PC and PinePhone is available as ready-to-use system image
-at the [https://genode.org/download/sculpt - Sculpt download page] accompanied
-with updated [https://genode.org/documentation/articles/sculpt-23-04 - documentation].
-
-
-Genode OS Framework release 23.02 | 2023-02-28
-##############################################
-
-| Version 23.02 introduces system-update functionality to the mobile version
-| of Sculpt OS, enhances our ARM VMM for interactive guest OSes, adds DMA
-| protection to Xilinx Zynq via a custom IP core, extends suspend/resume
-| support, and makes Intel's P&E cores explicitly manageable.
-
-For the first time, Genode has become easily installable on the PinePhone.
-The first system image is not merely a re-targeted PC version of Sculpt OS but
-it comes with a novel user interface, a new mechanism for rapidly switching
-between different application scenarios, and system-update functionality. This
-is everything we need to kick off the first public field test of Genode on the
-phone. This line of development motivated plenty of optimizations - from
-kernel scheduling, over the I/O throughput of the VFS, to the interfacing of
-GPU drivers - that made it into version 23.02.
-
-Besides the focus on the phone, the release continues the hardware-software
-co-design story of the previous version by adding DMA protection to Xilinx
-Zynq SoCs using custom FPGA fabric, which is especially tailored for Genode.
-But also stationary platforms like PCs and ARM laptops received attention.
-On ARM, we enabled the use of interactive virtual machines by adding
-device models for the GPU and input events. For the PC, the principle support
-for suspend/resume has become available to Genode's custom microkernel in
-addition to NOVA, and Genode learned to distinguish Intel's performance cores
-from energy-efficient cores.
-
-Regarding application workloads, the new release is accompanied by a
-substantially improved version of the Goa tool, which streamlines the
-creation, packaging, and publishing of Genode components using commodity
-build systems. With the new version, Goa largely automates the
-porting of CMake-based 3rd-party libraries for Genode.
-
-Find these among many more topics covered by the official
-[https:/documentation/release-notes/23.02 - release documentation of version 23.02...]
-
-
-Road Map for 2023 | 2023-01-17
-##############################
-
-| In 2023, we will make the mobile version of Sculpt OS fit for end users,
-| unleash advanced hardware features of Intel platforms,
-| switch to C++20 by default, and run the feature-complete PC version
-| of Sculpt OS on Genode's custom-tailored microkernel.
-
-After having enabled all hardware features of the PinePhone that are
-fundamental for a mobile phone over the course of the past year, the
-project now aims at getting the mobile version of Sculpt OS into the hands of
-end users. Throughout the year, there will be multiple rounds of field tests
-within the community, allowing us to reach the desired state of maturity and
-usefulness in an iterative way.
-
-On PC platforms, Genode will increasingly address advanced platform features
-like the distinction between power-efficient and high-performance cores, the
-management of temperatures and frequencies, or the practical use of
-suspend/resume. By the end of the year, we envision the PC version of Sculpt
-OS running on Genode's custom-tailored microkernel leveraging all those
-aspects of modern PC hardware.
-
-Along the planned timeline of the project, one can spot plenty of additional
-topics of interest such as the continued line of work of combining Genode
-with FPGAs, applications implemented in Rust, the integration of IPv6, the
-use of C++20 by default, or completed driver support for the MNT Reform laptop.
-An exciting year lies ahead of us!
-
-More details including our reflections of the past year, this year's focus,
-and a rough schedule are presented at our official
-[https:/about/road-map - road-map page].
-
-
-Genode OS Framework release 22.11 | 2022-11-30
-##############################################
-
-| Genode 22.11 enables hardware-accelerated graphics on up-to-date Intel
-| GEN12+ hardware, introduces work flows for hardware-software co-design,
-| wraps up the framework's unified device-driver infrastructure across PC and
-| ARM, and pushes forward the use of Genode on the PinePhone.
-
-The Genode OS framework is both a dependable foundation for custom operating
-systems - like Sculpt OS - and at the same time a playground for new ideas.
-The just released version 22.11 pays tribute to both facets. On the one hand,
-it features the results of our year-long effort of unifying and simplifying
-the framework's device-driver infrastructure across all base platforms, which
-subjects the interaction of driver components with device hardware to an
-unprecedentedly rigid regime of least privilege. This makes Genode-based
-systems ever more dependable and clear.
-
-The role of Genode as a playground for innovation is embodied by the
-combination of the framework with reconfigurable hardware. The release
-introduces new work flows for designing hardware IP cores and Genode
-components in tandem, which allows for low-complexity software-hardware
-co-designs that fit like a glove.
-
-Feature-wise, the new version covers a vast area of topics. The enhancement of
-our Intel GPU multiplexer to current GEN12+ hardware stands out most. Further
-topics range from the emerging user interface for Genode on the PinePhone,
-over plenty of device-driver work, to virtualization improvements on ARM and
-PC hardware.
-
-These and many more topics of the new version are covered by the official
-[https:/documentation/release-notes/22.11 - release documentation of version 22.11...]
-
-
 Sculpt OS release 22.10 | 2022-10-13
 ####################################
 

doc/release_notes/22-08.txt

@@ -400,7 +400,7 @@ We invite seasoned developers - especially those who are following the
 [https://genodians.org/nfeske/index - Pine-fun article series] - to experiment
 with the new phone variant. It can be built via the following command:
 
-! build/arm_v8a$ make run/sculpt KERNEL=hw BOARD=pinephone SCULPT=phone
+! built/arm_v8a$ make run/sculpt KERNEL=hw BOARD=pinephone SCULPT=phone
 
 For a broader audience, we plan to provide a ready-to-use SD-card image for
 the PinePhone in tandem with the next release of Sculpt OS.

doc/release_notes/23-02.txt

@@ -1,887 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 23.02
-              ===============================================
-
-                               Genode Labs
-
-
-
-With Genode's February release, almost everything goes
-[https://genode.org/about/road-map - according to plan].
-As envisioned on our road map, it features the first ready-to-install
-system image of Sculpt OS for the PinePhone, which is not merely a re-targeted
-version of the PC version but comes with a novel user interface, a new
-mechanism for rapidly switching between different application scenarios, and
-system-update functionality.
-Section [First system image of mobile Sculpt OS (PinePhone)] gives an
-overview and further links about running Genode on your PinePhone.
-
-While enabling substantial application workloads on devices as constrained as
-the PinePhone, we engaged in holistic performance optimizations, ranging from
-kernel scheduling (Section [Base-HW microkernel]), over the framework's VFS
-infrastructure (Section [VFS optimization and simplification]), to the
-interfacing of GPU drivers (Section [GPU performance optimizations]).
-
-For stationary ARM-based platforms like the MNT-Reform laptop,
-interactive graphical virtual machines have become available now, which
-brings us close to mirror the experience of the PC version of Sculpt OS on
-such devices (Section [Interactive graphical VMs on ARM]). This development
-is accompanied by several device-driver improvements for NXP's i.MX family.
-
-For embedded devices based on Xilinx Zynq, the release introduces custom
-FPGA fabric for implementing DMA protection that is normally not covered by
-Zynq SoCs. This line of work - as outlined in
-Section [Custom IP block for DMA protection on AMD/Xilinx Zynq] - exemplifies
-how well Genode and reconfigurable hardware can go hand in hand.
-
-Also, PC platforms got their share of attention, benefiting from the
-new distinction between Intel's P&E cores, or the principle support of
-suspend/resume on both NOVA and Genode's custom base-hw microkernel.
-
-When it comes to running applications on top of Genode, the release brings
-good news as well. Our custom Goa tool for streamlining
-application-development work flows received the ability to largely automate
-the porting and packaging of 3rd-party libraries using CMake
-(Section [Build system and tools]).
-
-
-First system image of mobile Sculpt OS (PinePhone)
-##################################################
-
-Just in time for our
-[https://fosdem.org/2023/schedule/event/genode_on_the_pinephone/ - public presentation]
-of Genode on the PinePhone at FOSDEM in the beginning of February,
-we published a first ready-to-use system image:
-
-:First system image of mobile Sculpt OS:
-
-  [https://genodians.org/nfeske/2023-02-01-mobile-sculpt]
-
-It features a
-[https://genodians.org/nfeske/2023-01-05-mobile-user-interface - custom user interface],
-voice calls and mobile-data connectivity, on-target software installation and
-system update, device controls (battery, brightness, volume, mic, reset,
-shutdown), and a variety of installable software. Among the installable
-applications, there is the Chromium-based Morph web browser, an OpenGL demo
-using the GPU, tests for the camera and microphone, as well as a light-weight
-Unix-like system shell.
-
-The underpinnings of the Genode system image for the PinePhone are nearly
-identical to Sculpt OS on the PC. However, besides the new user interface
-specifically designed for the touch screen of the phone, two noteworthy
-differences set it apart from the regular version of Sculpt OS.
-
-[image pinephone_presets]
-
-First, the phone variant allows the user to rapidly switch between different
-runtime configurations, called presets. This way, the limited resources of the
-phone can be accounted and fully leveraged for each preset individually, while
-making the system extremely versatile. The loading of a preset can be imagined
-as the boot into a separate operating system, but it takes only a fraction of
-a second. The structure of the running system is made fully transparent to the
-user by the component graph known from Sculpt OS.
-
-[image pinephone_scenarios]
-  The variety of presets includes the Morph browser, GLMark2, a system shell,
-  a simple oscilloscope, and camera test.
-
-Second, the system is equipped with an on-target system update mechanism that
-allows the user to install new versions of the system image when they become
-available. System updates are secured by cryptographic signatures. The
-mechanism does not only allow for updating the system but also for the
-rollback to any previously downloaded version. This way, the user can try
-out a new version while being able to fall back to the previous one in the
-case of a regression. This reinforces the end user's ultimate control.
-
-[image pinephone_update]
-
-
-Interactive graphical VMs on ARM
-################################
-
-The virtual-machine monitor (VMM) using hardware-assisted virtualization on
-ARM started as a case study eight years ago for Samsung's Exynos 5250 SoC.
-Originally, it supported virtualization of CPU, timer, interrupt-controller,
-and a UART-device only. Since then, it received several extensions like
-support for 64-bit ARMv8 systems, VirtIO devices for network, console, and
-block access. With release 22.11, the VMM's I/O device access, RAM
-consumption, and CPU count have come configurable.
-
-With the current release, we further enhance the VMM for ARM devices to
-provide all the means necessary to become a useful virtualization solution for
-interactive scenarios.
-
-[image mnt_interactive_debian_vm]
-  Sculpt OS running Debian in a virtual machine on the MNT Reform laptop
-
-Two additional VirtIO device models are available now: A GPU model and one for
-input. Both models are mapped to Genode's GUI service under the hood. One can
-extend the configuration of the VMM accordingly:
-
-! <config ...>
-!  <virtio_device name="fb0"    type="gpu"/>
-!  <virtio_device name="event0" type="input"/>
-!  ...
-! </config>
-
-For now, only one GPU and one input device can be declared. Both devices get
-mapped to the very same GUI service, according to the service routing of the
-VMM.
-
-Caution: the GPU and input model are still in an experimental state, and there
-are known corner cases, e.g., when the graphical window size of the VMM gets
-changed dynamically.
-
-Formerly, the VMM always expected an initial RAM file system to be provided as
-ROM dataspace, which got loaded together with the Linux kernel into the VM's
-memory. Now, it is possible to omit the "initrd_rom" configuration option.
-If omitted, no initrd is provided to the Linux guest.
-
-
-Custom IP block for DMA protection on AMD/Xilinx Zynq
-#####################################################
-
-As a continuation of the hardware-software co-design efforts presented in the
-[https://genode.org/documentation/release-notes/22.11#Hardware-software_co-design_with_Genode_on_Xilinx_Zynq - previous release],
-we turned towards enabling bulk-data transfer between the Zynq's CPU and its
-FPGA. In a first step, we built a custom hardware design that implements a DMA
-loopback device based on Xilinx' AXI DMA IP. Since we were particularly
-interested in testing out the Zynq's accelerator coherency port (ACP), we
-implemented two loopback devices: one attached to the ACP and one to the
-high-performance (HP) AXI port of the Zynq. In order to test the design in
-Genode, we added a port of Xilinx' embeddedsw repository that hosts standalone
-driver code for the Xilinx IP cores. Based on this port, we implemented the
-xilinx_axidma library as a Genode wrapper in order to simplify development of
-custom drivers using Xilinx' AXI DMA IP. A newly written test component takes
-throughput measurements for varying transfer sizes. A more detailed account of
-this story is published in an
-[https://www.hackster.io/johannes-schlatow/using-axi-dma-on-genode-6482d2 - article on hackster.io].
-
-Knowing that DMA bypasses any memory protection on the Zynq as it does not
-feature an IOMMU, we further spent some development efforts on implementing a
-custom IP block, called DMA Guard, for protecting against unintended DMA
-transfers from/to the FPGA. The DMA Guard is configured with a limited set of
-address ranges for which DMA transfers will be granted. Any out-of-range
-transfer will be denied. The configuration of the DMA Guard is conducted by
-the Zynq's platform driver based on the allocated DMA buffers. For the time
-being, we applied several changes to the platform driver. These modifications
-are currently hosted in the genode-zynq repository but are going to find their
-way into the generic platform driver for the next release.
-
-More details about the DMA Guard are covered by the dedicated article:
-[https://www.hackster.io/johannes-schlatow/taking-control-over-dma-transactions-on-zynq-with-genode-fd60b6 - Taking control over DMA transactions on Zynq with Genode].
-To follow this line of work, keep watching our
-[https://www.hackster.io/genode - hackster.io channel].
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-VFS optimization and simplification
-===================================
-
-For regular applications executed on Genode, input and output involves the
-virtual file system (VFS). In contrast to traditional monolithic operating
-systems (which host the VFS in the kernel) or traditional microkernel-based
-operating systems (which host the VFS in a dedicated server component),
-Genode's VFS has the form of a library, giving each component an individual
-virtual file system. The feature set of the VFS library is not fixed
-but extensible by so-called VFS plugins that come in the form of optional
-shared libraries. These plugins can implement new file-system types, but also
-expose other I/O facilities as pseudo files. For example, TCP/IP stacks like
-lwIP and lxIP (IP stack ported from Linux) have the form of VFS plugins.
-The extensibility of the VFS gives us extreme flexibility without compromising
-Genode's simplicity.
-
-On the other hand, the pervasiveness of the VFS - being embedded in Genode's C
-runtime - puts it on the performance-critical path whenever application I/O is
-involved. The ever-growing sophistication of application workloads like
-running a Chromium-based web browser on the PinePhone puts merciless pressure
-on the VFS, which motivated the following I/O-throughput optimizations.
-
-Even though the VFS and various VFS plugins work asynchronously, the batching
-of I/O operations is not consistently effective across different kernels. It
-particularly depends on the kernel's scheduling decision upon the delivery of
-asynchronous notifications. Kernels that eagerly switch to the signal receiver
-may thereby prevent the batching of consecutive write operations. We could
-observe variances of more than an order of magnitude of TCP throughput,
-depending on the used kernel. In the worst case, when executing a kernel that
-eagerly schedules the recipient of each asynchronous notification, the
-application performance is largely dominated by context-switching costs.
-
-Based on these observations, we concluded that the influence of the kernel's
-scheduler should better be mitigated by scheduling asynchronous notifications
-less eagerly at the application level. By waking up a remote peer not before
-the application stalls for I/O, all scheduled operations would appear at the
-remote side as one batch.
-
-The implementation of this idea required a slight redesign of the VFS,
-replacing the former implicit wakeup of remote peers by explicit wakeup
-signalling. The wakeup signalling is triggered not before the VFS user settles
-down. E.g., for libc-based applications, this is the case when the libc goes
-idle, waiting for external I/O. In the case of a busy writer to a non-blocking
-file descriptor or socket (e.g., lighttpd), the remote peers are woken up once
-a write operation yields an out-count of 0. The deferring of wakeup signals is
-accommodated by the new 'Remote_io' mechanism (_vfs/remote_io.h_) that is
-designated to be used by all VFS plugins that interact with asynchronous
-Genode services for I/O.
-
-Combined with additional adjustments of I/O buffer sizes - like the request
-queue of the file-system session, the TCP send buffer of the lwIP stack, or
-the packet buffer of the NIC session - the VFS optimization almost eliminated
-the variance of the I/O throughput among the different kernels and generally
-improved the performance. On kernels that suffered most from the eager context
-switching, netperf
-[https://github.com/genodelabs/genode/issues/4697#issuecomment-1342542399 - shows a 10x]
-improvement. But even on kernels with more balanced scheduling, the effect is
-impressive.
-
-While we were at it, and since this structural change affected all VFS plugins
-and users anyway, we took the opportunity to simplify and modernize other
-aspects of the VFS-related code as well.
-
-In particular, the new interface 'Vfs::Env::User' replaces the former
-'Vfs::Io_response_handler'. In contrast to the 'Io_response_handler', which
-had to be called on a 'Vfs_handle', the new interface does not require any
-specific handle. It is merely meant to prompt the VFS user (like the libc) to
-re-attempt stalled I/O operations but it does not provide any immediate hint
-about which of the handles have become ready for reading/writing. This
-decoupling led to welcome simplifications of asynchronously working VFS
-plugins.
-
-Furthermore, we removed the 'file_size' type from read/write interfaces. The
-former C-style pair of (pointer, size) arguments to those operations have been
-replaced by 'Byte_range_ptr' and 'Const_byte_range_ptr' argument types, which
-make the code safer and easier to follow. Also, the VFS utilities offered by
-_os/vfs.h_ benefit from this safety improvement.
-
-
-GPU performance optimizations
-=============================
-
-Session interface changes
--------------------------
-
-The GPU session interface was originally developed along the first version of
-our GPU multiplexer for Intel devices. For this reason, the interface
-contained Intel specific nomenclature, like GTT and PPGTT for memory map and
-unmap operations. With the introduction of new GPU drivers with different
-architectures (e.g., Mali and Vivante), the Intel specifics should have gone
-away. With the current Genode release, we streamlined the map and unmap
-functions to semantically be more correct on all supported hardware. There are
-two map functions now: First, _map_cpu_ which maps GPU graphics memory to be
-accessed by the CPU. And second, _map_gpu_ which establishes a mapping of
-graphics memory within the GPU.
-
-Additionally, we removed the concept of buffers (as used by Mesa and Linux
-drivers) to manage graphics memory and replaced it by the notion of video
-memory (VRAM) where VRAM stands for the actual graphics memory used by a GPU -
-may it be dedicated on-card memory or system RAM. The change makes it possible
-to separate the graphics-memory management from the buffer management as
-required by the Mesa library.
-
-
-Intel graphics
---------------
-
-When porting 3D applications using Mesa's OpenGL, we found that Mesa allocates
-and frees a lot of small GPU buffer objects (data in GPU memory) during
-operation. This is sub optimal for component-based systems because the Mesa
-library has to perform an RPC to the GPU multiplexer for each buffer
-allocation and for each buffer mapping. As mentioned above, we changed the
-session semantics from buffer object to video memory and implemented this
-feature within Intel's GPU multiplexer, which now only hands out VRAM. This
-made it possible to move the buffer handling completely to the Mesa client
-side (libdrm). Libdrm now allocates large chunks of video memory (i.e., 16MB)
-and hands out memory for buffer objects from this pool. This brings two
-advantages: First, the client-side VRAM pool acts as cache, which reduces the
-number of RPCs required for memory management significantly. Second, because
-of the larger VRAM allocations (compared to many 4K or 16K allocations before)
-fewer capabilities for the actual dataspaces that back the memory are
-required. Measurements showed that almost an order of magnitude of
-capabilities can be saved at Mesa or the client side this way.
-
-
-Mali graphics
--------------
-
-The 22.08 release introduced a
-[https://genode.org/documentation/release-notes/22.08#GPU_and_Mesa_driver_for_Mali-400 - driver]
-for the GPU found in the PinePhone. Since it was merely a rapid prototype, it
-was limited to one client at a time, and was normally started and stopped
-together with its client. With this release, we remedied these limitations and
-enabled support for multiple concurrent clients and also revised our libdrm
-backend for Mesa's Lima driver.
-
-We have not yet explored applying the same VRAM optimizations that are employed
-by our Intel graphics stack. One VRAM allocation still correlates to one
-buffer-object.
-
-
-More flexible ACPI-event handling
-=================================
-
-The _acpica_ component uses the Intel ACPICA library to parse and interpret
-ACPI tables and AML code. One designated feature is the monitoring of several
-ACPI event sources including optional reporting of information about state
-changes. The supported event sources are:
-
-* Lid, which can be open or closed
-* Smart battery (SB), information about battery parameters (e.g., capacity)
-  and charging/discharging status
-* ACPI fixed events, e.g., power buttons
-* AC adapters, which reflect power cable plug/unplug
-* Embedded controller (EC), events like Fn-* keys, Lid, AC, SB changes
-* Vendor-specific hardware events, e.g., Fujitsu FUJ02E3 key events
-
-Acpica optionally reports information about state changes. These reports can
-be monitored by other components as ROMs. The following configuration
-illustrates the feature:
-
-!<start name="report_rom">
-!  <resource name="RAM" quantum="2M"/>
-!  <provides> <service name="ROM" /> <service name="Report" /> </provides>
-!  <config>
-!    <policy label="acpi_event -> acpi_lid"     report="acpica -> acpi_lid"/>
-!    <policy label="acpi_event -> acpi_battery" report="acpica -> acpi_battery"/>
-!    <policy label="acpi_event -> acpi_fixed"   report="acpica -> acpi_fixed"/>
-!    <policy label="acpi_event -> acpi_ac"      report="acpica -> acpi_ac"/>
-!    <policy label="acpi_event -> acpi_ec"      report="acpica -> acpi_ec"/>
-!    <policy label="acpi_event -> acpi_hid"     report="acpica -> acpi_hid"/>
-!  </config>
-!</start>
-!
-!<start name="acpica">
-!  <resource name="RAM" quantum="8M"/>
-!  <config report="yes"/>
-!  <route>
-!    <service name="Report"> <child name="acpi_state"/> </service>
-!    ...
-!  </route>
-!</start>
-
-One such ACPI monitor component is _acpi_event_ that maps ACPI events to key
-events of a requested Event session based on its configuration. This way, ACPI
-state changes can be processed like ordinary key press-release events via, for
-example, the _event_filter_. The following configuration illustrates how to
-map the ACPI event types to key events:
-
-!<start name="acpi_event">
-!  <resource name="RAM" quantum="1M"/>
-!  <config>
-!    <map acpi="lid"   value="CLOSED"    to_key="KEY_SLEEP"/>
-!    <map acpi="fixed" value="0"         to_key="KEY_POWER"/>
-!    <map acpi="ac"    value="ONLINE"    to_key="KEY_WAKEUP"/>
-!    <map acpi="ec"    value="20"        to_key="KEY_BRIGHTNESSUP"/>
-!    <map acpi="ec"    value="21"        to_key="KEY_BRIGHTNESSDOWN"/>
-!    <map acpi="hid"   value="0x4000000" to_key="KEY_FN_F4"/>
-!  </config>
-!  <route>
-!    <service name="ROM" label="acpi_lid">     <child name="acpi_state"/> </service>
-!    <service name="ROM" label="acpi_battery"> <child name="acpi_state"/> </service>
-!    <service name="ROM" label="acpi_fixed">   <child name="acpi_state"/> </service>
-!    <service name="ROM" label="acpi_ac">      <child name="acpi_state"/> </service>
-!    <service name="ROM" label="acpi_ec">      <child name="acpi_state"/> </service>
-!    <service name="ROM" label="acpi_hid">     <child name="acpi_state"/> </service>
-!    <service name="Event"> <child name="event_filter" label="acpi"/> </service>
-!    ...
-!  </route>
-!</start>
-
-In the current release, we replaced the limited list of supported key names by
-a general mechanism, which supports the use of all key names declared in
-_repos/os/include/input/keycodes.h_.
-
-
-Base API changes
-================
-
-As part of our continuous motive to streamline and simplify the framework's
-base API as much as possible, the current release removes the interfaces
-_base/blocking.h_, _base/debug.h_, and _base/lock_guard.h_ as those headers
-contained parts of the API that have become obsolete by now. As a further
-minor change, the 'abs' function of _util/misc_math.h_ got removed.
-
-The string utilities _util/string.h_ received the new 'Const_byte_range_ptr'
-type complementing the existing 'Byte_range_ptr'. Both types are designated
-for passing arguments that refer to a byte buffer, e.g., the source buffer of
-a write operation.
-
-
-On-target system-update and rollback mechanism
-##############################################
-
-For the mobile version of Sculpt OS as covered in
-Section [First system image of mobile Sculpt OS (PinePhone)],
-we envisioned easy-to-use system updates that would enable us to quickly
-iterate based on the feedback of early field testers.
-
-This topic confronted us with a variety of concerns. Just to name a few,
-conventions for booting that would not require changes in the future,
-equipping (system) images with self-reflecting version information, tools for
-generating and publishing digitally-signed images, on-target discovery of new
-image versions, secure downloading and cryptographic checking of new images,
-directing the machine's boot loader to use the new version, and possibly
-reverting to an earlier version.
-
-Fortunately, most of these concerns have a lot in common with the problems
-we had to address for Genode's
-[https://genode.org/documentation/release-notes/18.02#On-target_package_installation_and_deployment - package management].
-For example, the off-target and on-target tooling for digital signatures,
-the notion of a depot, and the concept of federated software providers
-(depot users) are established and time-tested by now.
-
-
-Self-reflecting version information
------------------------------------
-
-To allow a running Sculpt system to know its own version, the sculpt.run
-script generates an artificial boot module named "build_info", which can be
-evaluated at runtime by the sculpt-manager component.
-
-! <build_info genode_version="22.11-260-g89be3404c0d"
-!             date="2023-01-19" depot_user="nfeske" board="pinephone">
-
-
-Formalism for generating images and image metadata
---------------------------------------------------
-
-To enable the Sculpt system to easily detect new versions, system images must
-be accompanied by metadata discoverable at a known location. This information
-is provided by a so-called image-index file located at
-_depot/<user>/image/index_. The image index of a depot user lists the
-available images in XML form, e.g.,
-
-! <index>
-!   <image os="sculpt" board="pinephone" version="2023-01-19">
-!      <info text="initial version"/>
-!   </image>
-!   ...
-! </index>
-
-The 'os', 'board', and 'version' attributes can be used to infer the file name
-of the corresponding image file. The '<info>' nodes contain a summary of
-changes as information for the end user.
-
-The new _gems/run/sculpt_image.run_ script provides assistance with generating
-appropriately named images, placing them into the depot, and presenting a
-template for the manually curated image index.
-
-
-Signing and publishing
-----------------------
-
-For signing and publishing system images and image indices, we extended the
-existing _tool/depot/publish_ tool. To publish a new version of an image
-index:
-
-! ./tool/depot/publish <depot-user>/image/index
-
-Each system image comes in two forms, a bootable disk image and an archive of
-the boot directory. The bootable disk image can be used to install a new
-system from scratch by copying the image directly to a block device. It
-contains raw block data. The archive of the boot directory contains the
-content needed for an on-target system update to this version. Within the
-depot, this archive has the form of a directory - named after the image - that
-contains the designated content of the boot directory on target. Depending on
-the board, it may contain only a single file loaded by the boot loader (e.g.,
-uImage), or several boot modules, or even the boot-loader configuration. The
-following command publishes both forms:
-
-! ./tool/depot/publish <depot-user>/image/<image-name>
-
-This results in the following - accompanied by their respective .sig
-files - in the public directory:
-
-! <depot-user>/image/<image-name>.img.xz  (disk image)
-! <depot-user>/image/<image-name>.tar.xz  (boot archive)
-! <depot-user>/image/<image-name>.zip     (disk image)
-
-The .zip file contains the .img file. It is provided for users who download
-the image on a system with no support for .xz.
-
-
-On-target image discovery, download, and verification
------------------------------------------------------
-
-To enable a running Sculpt system to fetch image index files and images, the
-existing depot-download component accepts the following two new download
-types:
-
-! <image_index path="<user>/image/index"/>
-! <image       path="<user>/image/<name>"/>
-
-Internally, the depot-download subsystem employs the depot-query component to
-determine the missing depot content. This component accepts the following two
-new queries:
-
-! <images      user="..."/>
-! <image_index user="..."/>
-
-If present in the query, depot_query generates reports labeled as "images" and
-"image_index" respectively. These reports are picked up by the depot-download
-component to track the completion of each job. The reported information is
-also used by the system updater to get hold of the images that are ready to
-install.
-
-
-On-target image installation and rollback
------------------------------------------
-
-Once downloaded into the local depot of a Sculpt system, the content of the
-boot directory for a given image version is readily available, e.g.,
-
-! depot/nfeske/image/sculpt-pinephone-2023-02-02/uImage
-
-The installation comes down to copying this content to the _/boot/_ directory.
-On the next reboot, the new image is executed.
-
-When subsequently downloading new image versions, the old versions stay
-available in the depot as sibling directories. This allows for an easy
-rollback by copying the boot content of an old version to the _/boot/_
-directory.
-
-
-Device drivers
-##############
-
-NXP i.MX Ethernet & USB
-=======================
-
-The Ethernet driver for i.MX53, i.MX6, and i.MX7 got updated to use a more
-recent Linux kernel version (5.11). These drivers got aligned with the
-source-code base originally ported for the i.MX8 SoC.
-
-Using the recent approach to port Linux device drivers, trying to preserve the
-original semantic, it is necessary to provide the correct clock rates to the
-driver. Therefore, specific platform drivers for i.MX6 and i.MX7 were created
-that enable the network related clocks and export their rate values.
-The i.MX53 related platform driver got extended to support these clocks.
-
-The USB host-controller driver for the i.MX 8MQ EVK is now able to drive the
-USB-C connector of this board too.
-
-
-Realtek Wifi
-============
-
-As a welcoming side effect of switching to the new DDE-Linux approach,
-enabling other drivers that are part of the same subsystem has become less
-involved. In the past, we mostly focused on getting wireless devices supported
-by the iwlwifi driver to work as those are the devices predominantly found in
-commodity laptops. That being said, every now and then, one comes across a
-different vendor and especially with the shifting focus on ARM-based systems
-covering those as well became necessary.
-
-As a first experiment, we enabled the rtlwifi driver that provides support
-for Realtek-based wireless devices. Due to lacking access to other hardware,
-the driver has been so far tested only with a specific RTL8188EE based device
-(10ec:8179 rev 01). Of course, some trade-offs were made as power-management
-is currently not available. But getting it to work, nevertheless, took barely
-half a day of work, which is promising.
-
-
-Platforms
-#########
-
-Base-HW microkernel
-===================
-
-Cache-maintenance optimization
-------------------------------
-
-On ARM systems, the memory view on instructions and data of the CPUs, as well
-as between CPUs and other devices is not necessarily consistent. When dealing
-with DMA transfers of devices, developers of related drivers need to ensure
-that corresponding cache lines are cleaned before a DMA transfer gets
-acknowledged. When dealing with just-in-time compilation, where instructions
-are generated on demand, the data and instruction caches have to be aligned
-too.
-
-Until now, the base-API functions for such cache-maintenance operations were
-mapped to kernel system calls specific to base-hw. Only the kernel was allowed
-to execute cache maintenance related instructions. On ARMv8 however, it is
-possible to allow unprivileged components to execute most of these
-instructions.
-
-With this release, we have implemented the cache maintenance functions outside
-the kernel on ARMv8 where possible. Thereby, several device drivers with a lot
-of DMA transactions, e.g. the GPU driver, benefit from this optimization
-enormously. The JavaScript engine used in the Morph and Falkon browsers
-profits as well.
-
-
-ACPI suspend & resume
----------------------
-
-In the previous release, we started to support the low-level
-[https://genode.org/documentation/release-notes/22.11#Low-level_mechanism_for_suspend_resume_on_PC_platforms - ACPI suspend and resume]
-mechanism with Genode for the NOVA kernel. With the current release, we added
-the required low-level support to Genode's base-hw kernel for x86 64bit
-platforms. Similar to the base-nova version, on base-hw the
-'Pd::managing_system' RPC function of Genode's core roottask is used to
-transfer the required ACPI values representing the S3 sleep state to the
-kernel. The kernel then takes care to halt all CPUs and flush its state to
-memory, before finally suspending the PC using the ACPI mechanism. On resume,
-the kernel re-initializes necessary hardware used by the kernel, e.g., all
-CPUs, interrupt controller, timer device, and serial device. One can test
-drive the new feature using the _run/acpi_suspend_ scenario introduced by the
-former release.
-
-
-Scheduling improvements for interactive workloads
--------------------------------------------------
-
-As Genode conquers the PinePhone, the base-hw kernel, for the first time, has
-to perform real-life multimedia on a daily basis given a resource-limited
-mobile target. One particularly important and ambitious use case has become
-video conferencing in the Morph browser. A combination of an already demanding
-browser engine with an application that not only streams video and audio in
-both directions over network but also handles video and audio I/O at the
-device, and all that fluently and at the same time.
-
-A lot of thinking went into how to optimize this scenario on each level of
-abstraction and one rather low-level lever was the scheduling scheme of the
-base-hw kernel. The base-hw scheduling scheme consists of a combination of
-absolute priority bands with execution-time quotas that prevent higher
-prioritized subjects from starving lower ones. There is the notion of a super
-period and each subject owns only a fraction of that super period as quota
-together with its priority. Once a subject has depleted its quota, it can't
-use its priority until the end of the current super period where its quota
-will be re-filled. However, during that time, the subject is not blocked - It
-can become active whenever there is no subject with priority and remaining
-quota present.
-
-So, this "zero" band below all the priority bands temporarily accommodates all
-subjects that have a priority but that are out of quota. It contains, however,
-also subjects that have no priority in general. These might be tasks like a GCC
-compilation or a ray tracer. While prioritized tasks would be user input
-handlers or the display driver. Now, one difficult problem that arises with
-this scheduling scheme is that system integration has to decide how much quota
-is required by a prioritized task. The perfect value can't be determined as it
-depends on many factors including the target platform. Therefore, we have to
-consider that an important task like the audio driver in the video-conference
-scenario runs out of quota shortly before finishing its work.
-
-This is already bad as is as the audio driver now has to share the CPU with
-many unimportant tasks until the next super period. But it became even worse
-because, in the past implementation, subjects always entered the zero band at
-the tail position. It meant that, e.g., the remaining audio handling had to
-wait at least until all the unprioritized tasks (e.g. long-taking computations)
-had used up their zero-band time slice. In order to mitigate this situation, we
-decided that prioritized tasks when depleting their quota become head of the
-zero-band, so, they will be scheduled first whenever the higher bands become
-idle.
-
-This change relaxes the consequences of quota-depletion events for
-time-critical tasks in a typical system with many unprioritized tasks.
-At the same time, it should not have a significant impact on the overall
-schedule because depletion events are rare and zero-band time-slices short.
-
-
-NOVA microhypervisor
-====================
-
-ACPI suspend & resume
----------------------
-
-As an extension to the principal
-[https://genode.org/documentation/release-notes/22.11#Low-level_mechanism_for_suspend_resume_on_PC_platforms - ACPI suspend and resume]
-support introduced with the Genode 22.11 release, the NOVA kernel now supports
-also the re-enablement of the IOMMU after ACPI resume. The IOMMU as a hardware
-feature has been supported by Genode since
-[https://genode.org/documentation/release-notes/13.02#DMA_protection_via_IOMMU - release 13.02]
-and extended in
-[https://genode.org/documentation/release-notes/20.11#NOVA_microhypervisor - release 20.11],
-which sandboxed device hardware and (malicious/faulty) drivers to avoid
-arbitrary DMA transactions.
-
-Intel P/E cores
----------------
-
-Starting with [https://en.wikipedia.org/wiki/Intel_Core#12th_generation - Intel CPU generation 12],
-Intel introduced CPUs with heterogeneous cores, similar to
-[https://en.wikipedia.org/wiki/ARM_big.LITTLE - ARM's big/LITTLE] concept.
-The new CPUs have a number of so called P-cores (performance) and E-cores
-(efficient), which differ in their performance and power characteristics.
-The CPU cores
-([https://en.wikipedia.org/wiki/Alder_Lake#CPUID_incoherence - should be])
-instruction compatible and are reported as identical via x86's CPUID
-instruction nowadays. However, an operating system such as Genode must be able
-to differentiate the cores in order to take informed decisions about the
-placement and scheduling of Genode components.
-
-With the current release, we added support to the NOVA kernel to propagate the
-information about P/E cores to Genode's 'core' roottask. In Genode's core,
-this information is used to group the CPU cores into Genode's
-[https://genode.org/documentation/release-notes/13.08#Management_of_CPU_affinities - affinity space].
-With
-[https://genode.org/documentation/release-notes/20.05#NOVA_microhypervisor - release 20.05],
-we introduced the grouping of hyperthreads on the y-axis, which we keep in
-case the P-cores have the feature enabled. Following the P-cores and
-hyperthreads, all remaining E-cores are placed in the affinity space.
-
-The following examples showcase the grouping in the affinity-space on x/y axis:
-
-Core i7 1270P - 4 P-cores (hyperthreading enabled) and 8 E-cores:
-
-! x-axis      1  2  3  4  5  6  7  8
-! ----------------------------------
-! y-axis  1 | P\ P\ P\ P\ E  E  E  E
-!         2 | P/ P/ P/ P/ E  E  E  E
-!
-! hyperthreads \ / of same core
-
-Core i7 1280P - 6 P-cores (hyperthreading enabled) and 8 E-cores:
-
-! x-axis      1  2  3  4  5  6  7  8  9  10
-! -----------------------------------------
-! y-axis  1 | P\ P\ P\ P\ P\ P\ E  E  E  E
-!         2 | P/ P/ P/ P/ P/ P/ E  E  E  E
-!
-! hyperthreads \ / of same core
-
-The information about the P/E cores is visible in the kernel and Genode's
-log output and is reported in the 'platform_info' ROM, e.g.
-
-! kernel:
-!
-! [ 0] CORE:00:00:0 6:9a:3:7 [415] P 12th Gen Intel(R) Core(TM) i7-1270P
-! ...
-! [15] CORE:00:17:0 6:9a:3:7 [415] E 12th Gen Intel(R) Core(TM) i7-1270P
-! ...
-
-! Genode's core:
-!
-! mapping: affinity space -> kernel cpu id - package:core:thread
-!  remap (0x0) ->  0 - 0: 0:0 P boot cpu
-!  remap (0x1) ->  1 - 0: 0:1 P
-!  remap (1x0) ->  2 - 0: 4:0 P
-!  remap (1x1) ->  3 - 0: 4:1 P
-!  remap (2x0) ->  4 - 0: 8:0 P
-!  remap (2x1) ->  5 - 0: 8:1 P
-!  remap (3x0) ->  6 - 0:12:0 P
-!  remap (3x1) ->  7 - 0:12:1 P
-!  remap (4x0) ->  8 - 0:16:0 E
-!  remap (4x1) ->  9 - 0:17:0 E
-!  remap (5x0) -> 10 - 0:18:0 E
-!  remap (5x1) -> 11 - 0:19:0 E
-!  remap (6x0) -> 12 - 0:20:0 E
-!  remap (6x1) -> 13 - 0:21:0 E
-!  remap (7x0) -> 14 - 0:22:0 E
-!  remap (7x1) -> 15 - 0:23:0 E
-! ...
-
-! platform_info ROM:
-!
-! ...
-! <cpus>
-!   <cpu xpos="0" ypos="0" cpu_type="P" .../>
-!   ...
-!   <cpu xpos="5" ypos="0" cpu_type="E" .../>
-!   ...
-! <cpus>
-! ...
-
-
-Build system and tools
-######################
-
-Building and packaging CMake-based shared libraries (via Goa)
-=============================================================
-
-The [https://github.com/nfeske/goa - Goa] tool streamlines the work of
-cross-developing, testing, and publishing Genode application software
-using commodity build tools like CMake. The tool is particularly suited for
-porting existing 3rd-party software to Sculpt OS.
-
-Until recently, Goa was solely focused on applications whereas the porting of
-3rd-party libraries required the use of the traditional approach of hand
-crafting build rules for Genode's build system. This limitation of Goa got
-lifted now.
-
-In the new version, a Goa project can host an _api_ file indicating that
-the project is a library project. The file contains the list of headers that
-comprise the library's public interface. The build artifact of a library
-is declared in the _artifacts_ file and is expected to have the form
-_<library-name>.lib.so_. The ABI symbols of such a library must be listed
-in the file _symbols/<library-name>_. With these bits of information supplied
-to Goa, the tool is able to build and publish both the library and the API as
-depot archives - ready to use by Genode applications linking to the library.
-The way how all those little pieces work together is best illustrated by the
-accompanied
-[https://github.com/nfeske/goa/tree/master/examples/cmake_library - example].
-For further details, please consult Goa's builtin documentation via 'goa help'
-(overview of Goa's sub commands and files) and 'goa help api' (specifics of
-the _api_ declaration file).
-
-When porting a library to Genode, one manual step remains, which is the
-declaration of the ABI symbols exported by the library. The new sub command
-'goa extract-abi-symbols' eases this manual step. It automatically generates a
-template for the _symbols/<library-name>_ file from the library's built shared
-object. Note, however, that the generated symbols file is expected to be
-manually reviewed and tidied up, e.g., by removing library-internal symbols.
-
-_Thanks to Pirmin Duss for having contributed this welcomed new feature, which_
-_makes Goa much more versatile!_
-
-
-New tool for querying metadata of ports
-=======================================
-
-The integration of third-party software into Genode is implemented via _ports_
-that specify how to retrieve, verify, and patch the source code in preparation
-for use with our build system. Ports are managed by tools residing in the
-_tool/ports_ directory. For example, _tool/ports/prepare_port_ is used to
-execute all required preparation steps.
-
-Currently, the base Genode sources support 90 ports (you may try
-_tool/ports/list_ yourself) and, thus, it's not trivial to keep track of all
-the ports in the repo directories. Therefore, we introduce the
-_tool/ports/metadata_ tool to extract information about license, upstream
-version, and source URLs of individual ports. The tool can be used as follows:
-
-!./tool/ports/metadata virtualbox6
-!
-!PORT:     virtualbox6
-!LICENSE:  GPLv2
-!VERSION:  6.1.26
-!SOURCE:   http://download.virtualbox.org/virtualbox/6.1.26/VirtualBox-6.1.26.tar.bz2 (virtualbox)
-!SOURCE:   http://download.virtualbox.org/virtualbox/6.1.26/VirtualBoxSDK-6.1.26-145957.zip (virtualbox_sdk)
-
-
-Harmonization of the boot concepts across ARM and PC platforms
-==============================================================
-
-To make the system-update functionality covered in
-Section [On-target system-update and rollback mechanism] equally usable across
-PC and ARM platforms, the conventions of booting the platforms had to be
-unified.
-
-Traditionally, a bootable disk image for the PC contains a _boot/_ directory.
-E.g., when using NOVA, it contains the GRUB boot-loader config + the hypervisor +
-the bender pre-boot loader + the banner image + the Genode system image.
-This structure corresponds 1:1 to the _boot/_ directory as found on the 3rd
-partition of the Sculpt system, which is very nice. A manual system update of
-Sculpt comes down to replacing these files. However, on ARM platforms, SD-card
-images used to host a _uImage_ file and a U-Boot environment configuration
-file in the root directory. The distinction of these differences complicates
-both the build-time tooling and the on-target handling of system updates.
-
-The current release unifies the boot convention by hosting a _boot/_ directory
-on all platforms and reinforces the consistent naming of files. On ARM, the
-_uImage_ and _uboot.env_ files now always reside under _boot/_. Thanks to this
-uniform convention, Genode's new system update mechanism can now equally
-expect that a system update corresponds to the mere replacement of the content
-of the _boot/_ directory.
-
-
-Minor run-tool changes
-======================
-
-The functionality of the _image/uboot_fit_ plugin has been integrated into the
-regular _image/uboot_ plugin as both plugins were quite similar.
-FIT images can now be produced by adding the run option '--image-uboot-fit'.
-

doc/release_notes/23-05.txt

@@ -1,861 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 23.05
-              ===============================================
-
-                               Genode Labs
-
-
-
-Besides our annual documentation update, our major tool-chain update as
-scheduled every two years, and the switch to C++20, version 23.05 puts the
-spotlight on the Goa tool, which allows us to leverage existing SDKs like
-Lomiri and Rust's cargo for Genode applications. In line with the previous
-versions, DDE-Linux is prominently featured as enabler of our cross-platform
-Wifi stack and the updated (6.1.20) drivers for Intel graphics and USB.
-
-: <div class="visualClear"><!-- --></div>
-: <p>
-:  <div style="clear: both; float: left; margin-right:20px;">
-:   <a class="internal-link" href="https://genode.org/documentation/genode-foundations-23-05.pdf">
-:    <img class="image-inline" src="https://genode.org/documentation/genode-foundations-title.png">
-:   </a>
-:   <a class="internal-link" href="https://genode.org/documentation/genode-platforms-23-05.pdf">
-:    <img class="image-inline" src="https://genode.org/documentation/genode-platforms-title.png">
-:   </a>
-:  </div>
-: </p>
-
-Before getting to the technical achievements, we'd like to draw your attention
-to the books "Genode Foundations" and "Genode Platforms", which have been
-updated to reflect the most recent state of the framework. Whereas the
-"Foundations" cover Genode's architecture, developer work flows, and reference
-material, the "Platforms" document is focused on low-level hardware topics and
-provides plenty of practical guidance.
-
-: <div class="visualClear"><!-- --></div>
-
-Every two years, we update Genode's tool chain to the latest stable releases
-of GCC and binutils. This time, we took the update as opportunity to switch
-Genode's default from C++17 to C++20 so that modern C++ niceties can be used
-for regular Genode components. The new tool chain is covered by
-Section [New tool chain based on GCC 12.3, C++20 enabled by default].
-
-For application developers, the evolving Goa tool is certainly the most
-interesting feature of the current release. As detailed in
-Section [Goa tool updated to Sculpt OS 23.04, initial support for Rust],
-this tool enables us to reuse existing SDKs to target Genode. In particular,
-we enabled the use of the Lomiri mobile UI toolkit (formerly known as Ubuntu
-Touch UI toolkit) for targeting the PinePhone, and Rust's cargo.
-
-System integrators may appreciate our continued development of the Linux
-device-driver environment, which received an update to Linux 6.1.20
-(Section [Device drivers]) and ultimately enabled us to use the same Wifi
-stack across PC and ARM platforms
-(Section [Uniform Wifi stack across PC and ARM platforms]).
-
-Even though not end-user facing yet, two noteworthy development milestones of
-the current release are the new use of our custom base-hw microkernel as x86
-hypervisor (Section [Base-HW microkernel]) and the profound work on storage
-encryption covered in
-Section [Revision of Genode's custom block-encryption infrastructure].
-Further topics making an appearance in version 23.05 range from RISC-V, over
-WireGuard, VirtualBox, to seL4.
-
-
-Goa tool updated to Sculpt OS 23.04, initial support for Rust
-#############################################################
-
-Last month, we [https://genode.org/news/sculpt-os-release-23.04 - released]
-Sculpt OS 23.04 for PC and PinePhone. The new release comes with various
-[https://genodians.org/nfeske/2023-05-11-sculpt-os - usability improvements]
-such as presets and on-target system updates.
-
-[image mobile_sculpt_23_04]
-  Interactive software management on the mobile variant of Sculpt OS
-
-In particular, with Sculpt OS 23.04 running on the PinePhone, we have carved
-out the base for hosting mobile apps on a Genode-based system. Yet, there are
-only very few apps available right now. Since an OS is of no practical use
-without apps, this urgently called for an SDK to simplify (mobile) app
-development. After careful investigation, we opted for porting the
-Ubuntu-Touch-UI toolkit to Genode and integrate it into Goa (Section
-[Using Goa for bringing apps based on the Ubuntu-Touch-UI toolkit to Genode]),
-our streamlined workflow tool for application development. In addition, we
-integrated initial support for Rust's _cargo_ to make Goa palatable to a
-broader developer audience (Section [Initial Rust support]).
-
-The growing attention of the Goa tool prompted us to move it under the
-[https://genodians.org/nfeske/2023-05-02-goa-genode-labs - umbrella of Genode Labs]
-as we are increasing our development and maintenance efforts for the tool.
-Aligned with the Sculpt release, the Goa tool has been updated with the
-corresponding depot archive versions. With this Genode release, we put a
-cherry on top and added bash completion to improve the user experience even
-further. Having Goa installed, bash completion is enabled by the following
-commands:
-
-! goa update-goa master
-! GOA_DIR=$(realpath $(which goa) | sed s#bin/goa##)
-! echo "source ${GOA_DIR}/share/bash-completion/goa" >> ~/.bashrc
-
-:Goa tool:
-
-  [https://github.com/genodelabs/goa/]
-
-
-Using Goa for bringing apps based on the Ubuntu-Touch-UI toolkit to Genode
-==========================================================================
-
-While writing mobile apps might be fun, it is outside our core expertise.
-Therefore, we have looked into ways of supporting established open-source SDKs
-for app development on Genode. We investigated two possible options in depth,
-namely Ubuntu Touch's UI toolkit now called [https://lomiri.com - Lomiri] and
-the [https://docs.sailfishos.org/Tools/Sailfish_SDK - Sailfish SDK]. We have
-tried to port applications for both stacks and after many iterations settled
-with the Ubuntu UI toolkit. The full story can be read
-[https://genodians.org/ssumpf/2023-05-06-ubunutu_ui - here]. Therefore, a port
-of the Ubuntu UI toolkit is available on Genode right now and support for it
-has been added to the Goa tool.
-
-The workflow for crafting an app for the PinePhone using the Goa tool is a
-fairly streamlined experience now:
-
-# Since the UI toolkit depends on Qt5, add "genodelabs/api/qt5" to your
-  [https://genodians.org/nfeske/2019-11-25-goa - _used_apis_ file]
-
-# Add "ssumpf/pkg/ubuntu_ui_toolkit" to your _archives_
-  [https://genodians.org/nfeske/2019-11-25-goa - file] to have the UI toolkit
-  available within your package
-
-# In order to have your QML code within your packet installed, add
-  "<packet-name>.tar: install/" to your
-  [https://genodians.org/nfeske/2019-11-25-goa - _artifacts_ file]
-
-# Configure your
-  [https://genodians.org/nfeske/2019-12-19-goa-unix-terminal - _runtime_ file]
-
-# Execute your scenario on Linux for development
-  ! goa run
-
-# Build for the PinePhone
-  ! goa build --arch arm_v8a
-
-# [https://genodians.org/nfeske/2020-01-16-goa-publish - Publish] your package
-  ! goa publish --depot-user john --depot-overwrite
-
-Examples using QML, Qt5, and C++ can be found
-[https://github.com/ssumpf/goa-projects - here]
-
-
-Initial Rust support
-====================
-
-The Rust programming language has grown in popularity in the recent years.
-The Genode OS Framework had support for the Rust programming language
-before, contributed to Genode release 16.05 by Waylon Cude. However, as an
-on-off contribution it never got traction and the support was eventually
-removed with release 20.05.
-While the original support focused on some low-level runtime libraries and
-integration into the Genode build system, our new attempt has a somewhat
-different objective, which is to facilitate the use of the existing Rust
-ecosystem on the Genode OS Framework. The removal note already envisioned a
-possible comeback using the Goa tool and Rust's cargo build system, for which
-we have added initial support with this release.
-
-Our objective led to the following guidelines for Rust integration:
-
-# Make use of the native build system, cargo, to make the existing ecosystem
-  accessible.
-# Aim for a seamless integration into the Genode OS Framework using the Goa
-  build tool.
-# Instead of introducing our own Genode
-  [https://doc.rust-lang.org/nightly/rustc/platform-support.html - target triples],
-  leverage Genode's FreeBSD-based C library interface to use existing
-  supported standard library targets like 'x86_64-unknown-freebsd'.
-# Strive to use the upstream tool chain, or at least stay as close to upstream
-  as possible.
-
-While we largely succeeded in following these guidelines, our initial
-proof-of-concept implementation relies on a marginally adapted tool chain to
-work around missing support for versioned library symbols in our linker.
-We are exploring avenues to overcome these limitations and expand the support
-to cover more complex use cases in the next release.
-
-To learn more about our Rust support, head over to the
-[https://genodians.org/atopia/2023-05-30-bringing-rust-back-to-genode - article on Genodians.org].
-
-
-Uniform Wifi stack across PC and ARM platforms
-##############################################
-
-Support for wireless LAN was mostly focused on the
-[https://genode.org/documentation/release-notes/14.11#Intel_wireless_stack - PC platform]
-as it was the platform predominately used for using Genode and, in extension,
-Sculpt on a daily basis. In the last couple of years, however, we started to
-embrace ARM-based platforms like the MNT Reform 2 and the PinePhone as well,
-longing for thorough support of Sculpt OS on such systems. Thanks to our Linux
-device-driver environment, we have now taken the opportunity to reuse the
-existing wireless stack on vastly different platforms.
-
-
-Making the wireless stack globally accessible
----------------------------------------------
-
-The
-[https://genode.org/documentation/release-notes/23.02#Realtek_Wifi - previous release]
-already featured additional support for a different wireless LAN device driver -
-the rtlwifi driver that supports Realtek-based devices - giving us a good
-intuition on how easy it has become to extend even a complex Linux-based
-driver component stack such as our wifi-driver component ('wifi_drv').
-
-The first step was making it less x86-centric. We started by making the various
-ingredients of the driver available on the ARM platforms.
-
-On the one hand, that includes the WPA supplicant and its dependencies like
-the 'nl80211' driver that in turn depends on 'libnl'. Enabling them was
-straight-forward because they are already pretty platform independent and
-the platform-dependent portions, e.g. libcrypto, are readily available for ARM.
-
-On the other hand, the wireless stack was slightly more complicated because
-the hardware integration of wireless networking devices on ARM platforms
-varies from platform to platform. In case of the MNT Reform 2 and PC, the
-integrated wireless devices are normally connected via PCIe. In contrast, the
-PinePhone relies on SDIO. We separated the code to allow for a "mix-and-match"
-way of selecting the necessary compilation units as the used Linux
-configuration might differ between each target and could result in compilation
-issues otherwise.
-
-The next step was to make the wireless stack globally accessible by moving it
-from the _pc_ to the _dde_linux_ repository. This move was motivated by the
-fact that the _dde_linux_ repository is already available in all platform or
-rather board-specific repositories while the _pc_ repository is not. It is
-in itself a board-specific repository and therefore having it appear as
-dependency for other such repositories feels unnatural.
-
-So the bulk of the driver code now lives in the _dde_linux_ repository from
-where it can be referenced by other repositories.
-
-While moving the code, we noticed that in contrast to all other Linux-based
-drivers the 'wifi_drv' is special. Since the binary itself is a libc component,
-care was taken to isolate the application code, the 'wpa_supplicant', from
-the driver code, the library containing the Linux wireless stack and drivers.
-On all platforms, the binary stays the same while the driver library contains
-all the platform-specific code. For this reason, the 'wifi_drv' binary is now
-delegated to be a generic harness that includes all configuration and
-management functionality shared by all wireless device driver components,
-e.g., the WPA supplicant. The code of the device driver emulation environment
-is located in _repos/dde_linux/src/lib/wifi_. It is referenced by the
-platform-specific driver library that resides in the corresponding platform
-repository. The runtime configuration needs to point the driver to a proper
-driver library.
-
-The platform-specific library is in charge of orchestrating the 3rd-party
-sources utilized by the driver as well as providing the _source.list_ and
-_dep.list_ files. It must include the generic library snippet
-_repos/dde_linux/lib/wifi.inc_ that deals with managing the emulation
-environment code. The amount of code added by the platform-specific libraries
-is unimposing as it mostly consists of the dummy implementations needed by
-the Linux configuration.
-
-[image wifi_drv_architecture]
-  Composition of the wireless LAN driver component
-
-All recipes for the depot archives are prefixed to the specific driver, for
-example 'pkg/pc_wifi' contains a reference to 'src/pc_wifi_drv' as well as to
-'raw/pc_wifi_firmware'.
-
-Thanks to the steps outlined above, we now have three different wireless LAN
-drivers, one for the PinePhone, one for the MNT Reform 2, and one for the PC
-that nicely follow the same approach.
-
-
-New firmware loading mechanism
-------------------------------
-
-Additionally to making it easier to enable and use the driver for new
-platforms, we also refined how the driver loads its firmware images. In the
-past, the driver contained a list of well-known working firmware images that
-needed to be updated every now and then when new devices where enabled or the
-firmware version changed due to a Linux update. In particular using the driver
-with new devices was cumbersome as the driver itself already supported the
-device most of the time, but it solely missed the corresponding entry in the
-firmware list and adding that required recompiling the driver.
-
-[image wifi_firmware_loading]
-  Firmware image loading sequence
-
-So instead, the driver now loads the firmware images via its local VFS rather
-than requesting a predetermined ROM module. Since the platform-specific driver
-library has no direct access to the VFS - after all both worlds are
-intentionally isolated from each other - a request/response interface was
-added. The library submits a request to the _wifi_drv_ binary and will suspend
-its execution waiting for the completion of the request. The binary will
-acquire the firmware image and notify the driver library in return.
-Streamlining the firmware acquisition in such a manner allows for using the
-original probing mechanism available in Linux. Rather than following the
-firmware list the actual driver code is now free to probe as it sees fit,
-exactly pointing to the required uAPI revision in case the firmware is
-missing.
-
-The following snippet illustrates the configuration of the driver on the
-PinePhone (omitting any integration-related routes for the config ROM as well
-as state and scan reports):
-
-!<start name="wifi_drv" caps="250" priority="-1">
-!  <resource name="RAM" quantum="32M"/>
-!  <config ld_verbose="yes">
-!    <report mac_address="true"/>
-!    <libc stdout="/dev/log" stderr="/dev/log"
-!          rtc="/dev/rtc" rng="/dev/urandom"/>
-!    <vfs>
-!      <dir name="dev"> <log/> <null/> <rtc/>
-!        <jitterentropy name="random"/>
-!        <jitterentropy name="urandom"/>
-!        <wifi/>
-!      </dir>
-!      <dir name="firmware">
-!        <tar name="wifi_firmware.tar"/>
-!      </dir>
-!    </vfs>
-!  </config>
-!  <route>
-!    <service name="ROM" label="wifi.lib.so">
-!      <parent label="a64_wifi.lib.so"/>
-!    </service>
-!    <service name="ROM" label="wifi_firmware.tar">
-!      <parent label="a64_wifi_firmware.tar"/>
-!    </service>
-!    <service name="ROM" label="dtb">
-!      <parent label="wifi-pinephone.dtb"/>
-!    </service>
-!    […]
-!    <any-services> <parent/> <any->child/> </service>
-!  </route>
-!</start>
-
-In this configuration, the firmware images are provided as a _.tar_ archive
-that itself is requested via a ROM connection. The driver will always look
-into the _/firmware_ directory to access any firmware related files. How the
-directory is populated is up to the integrator of the driver.
-
-As a further simplification step, we removed the need for the firmware library
-used to contain firmware images. It is superseded by the use of a plain data
-depot archive, e.g., _raw/pc_wifi_firmware_.
-
-
-Additional device support and updates
--------------------------------------
-
-We updated the firmware images to the most recent ones supported by
-Linux version 6.1.20.
-
-We enabled the ath9k PCIe driver that can be used on the MNT Reform 2 and the
-PC. As the ath9k device (168c:0034) used to test the driver on the PC exhibited
-problems when using MSIs, we disable their usage in the 'pci_decoder'. Similar
-treatment might be necessary if other ath9k-based devices are used.
-
-The device support in the 'rtlwifi' driver got extended by additionally
-enabling support for RTL8192CE devices.
-
-Furthermore, we updated the WPA supplicant to its latest v2.10 release and
-introduce preliminary support for joining networks secured by WPA3.
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-New tool chain based on GCC 12.3, C++20 enabled by default
-==========================================================
-
-Following a regular cycle of two years, we updated our tool chain to recent
-versions again, this time in particular to GCC 12.3.0, binutils 2.40, and GDB
-13.1 while taking the opportunity to enable C++20 by default.
-
-A noticeable change with GCC 12 is that auto-vectorization with the
-'-ftree-vectorize' option is now enabled by default when building with the
-'-O2' optimization level. This has the effect that more SIMD instructions are
-generated, which required adaptations throughout our code base, for example by
-making sure that memory allocations in ported Linux drivers adhere a suitable
-address alignment and by saving and restoring ARMv8 FPU registers in the
-dynamic linker.
-
-In addition to that, GCC 12 reports new warnings and errors, which we had to
-rectify at various places, the most common ones being:
-
-* Deprecated arithmetics between different enumeration types,
-
-* Deprecated use of '++' and '--' operators with volatile variables, and
-
-* Undefined references to 'strlen' inside custom implementations
-  of 'strlen'-like functions, related to the
-  '-ftree-loop-distribute-patterns' option.
-
-As an extra feature, we added Genode's library name patterns to the linker so
-that the '-l' option has become able to find the corresponding libraries.
-This is useful while porting 3rd-party software based on Autoconf, whenever a
-'configure' script checks for a library dependency by linking a test program
-with this option. This change thereby removes the need for dummy libraries
-that were formerly used to satisfy the probing.
-
-
-API changes
-===========
-
-As part of Genode's
-[https://genode.org/documentation/release-notes/16.08#Cultivation_of_the_new_text-output_API - great API revision]
-in 2016, we largely *abolished* the use of *format strings* throughout the
-framework. This is desirable because a code base without format strings cannot
-have format-string vulnerabilities. Still, a few occurrences, specifically the
-interface for passing session-construction arguments, remained untouched since
-then. With version 23.05, we finally attained our initial goal by wrapping up
-the transition.
-
-In particular, we revised 'Genode::Connection', which now accepts the session
-label, affinity, and session-specific parameters as constructor arguments,
-whereas the parameters are passed as a 'Genode::String'. This eliminates the
-need for rendering a format string. Given this new interface, we were able to
-remove format strings from all connection types, updated all components that
-still happened to rely on format strings, and ultimately removed format
-strings from Genode's base API.
-
-Format strings still play a role to accommodate 3rd-party code ported
-to Genode. Whenever the 3rd-party code targets the C runtime, format
-strings are readily available via the libc. For free-standing ports that
-avoid the dependency from the full C runtime, e.g., ported device drivers,
-a new 'format' library based on Genode's former _base/snprintf.h_ and
-_base/console.h_ provides rudimentary format-string support. The library
-is hosted in the libports repository.
-
-As another matter of housekeeping, we removed the _util/avl_string.h_ utility.
-The use case of organizing objects by using strings as keys is covered by the
-_util/dictionary.h_ now.
-
-
-Towards kernel-agnostic DMA protection
-======================================
-
-As sketched in our [https://genode.org/about/road-map - road map], we plan
-having a feature-complete PC version of Sculpt OS based on base-hw by the end
-of this year. One of the reasons why we are still sticking to base-nova for
-the PC version is the fact that we are relying on NOVA's IOMMU support. One
-necessary step to decouple Sculpt OS from base-nova is to integrate the IOMMU
-handling into the platform driver.
-
-Motivated by our
-[https://genode.org/documentation/release-notes/23.02#Custom_IP_block_for_DMA_protection_on_AMD_Xilinx_Zynq - custom IP block for DMA protection on AMD/Xilinx Zynq],
-we integrated the notion of IOMMU-like devices into the platform driver with
-this release as a preparatory step. The platform driver automatically acquires
-known IOMMU-like devices for itself by looking at the device types. Other
-devices can then reference these devices by using '<io_mmu>' nodes. This is
-best illustrated by looking at the devices ROM for the Zynq's dma_guard IP
-block:
-
-! <devices>
-!
-!   <device type="dma_guard" name="dma_guard_0">
-!     <!-- [...] -->
-!   </device>
-!
-!   <device type="axi_dma" name="axi_dma_0">
-!     <io_mmu name="dma_guard_0"/>
-!     <!-- [...] -->
-!   </device>
-!
-! </devices>
-
-This tells the platform driver that, whenever a DMA buffer is allocated/freed
-for the session owning the 'axi_dma_0' device, the 'dma_guard_0' must be
-configured accordingly in order to allow/deny access to the corresponding
-memory ranges. With the structural changes to the platform driver, the support
-for dma_guard devices is simply added by implementing specific 'Io_mmu' and
-'Io_mmu_factory' objects. You can find the code in the _dma_guard.h_ within
-the
-[https://github.com/genodelabs/genode-zynq/blob/master/src/drivers/platform/zynq/dma_guard.h - genode-zynq repo].
-
-For the PC version of the platform driver, we implemented a _kernel_iommu_
-device that still uses device PDs to pass IOMMU configuration to the NOVA
-kernel. The _kernel_iommu_ is automatically instantiated and used as a default
-for each device until we replaced this by a kernel-agnostic implementation in
-a future release.
-
-With these preparations, we paved the way for implementing configuration logic
-for arbitrary IOMMU-like devices within the platform driver. In particular,
-the platform driver has been made capable of managing multiple IOMMU-like
-devices at the same time. However, there is one limitation that comes from the
-fact that DMA buffers are not device-specific but allocated per session: All
-IOMMU-like devices must either operate as MMU (virtual addressing) or as MPU
-(physical addressing).
-
-
-Revision of Genode's custom block-encryption infrastructure
-===========================================================
-
-Tresor library
-~~~~~~~~~~~~~~
-
-For about two years, our Ada/SPARK-based CBE block encryption and its GUI
-front-end, the file vault, served us well with rather manageable workloads
-such as configuration and credential files in Sculpt OS on the PC. However,
-with the rise of mobile Sculpt on the PinePhone, the CBE ecosystem was
-suddenly confronted with new challenges and requirements.
-
-First, mobile platforms are usually less forgiving when it comes to
-performance and the CBE still exhibited a lot of potential for optimization.
-Second, we envision encrypted storage to become an integral part of the base
-system - the "appliance role" of mobile Sculpt OS - which shifts the role of
-the component from an optional feature to a foundational mechanism. With this
-role shift, however, maintainability becomes increasingly important. Third,
-now that we decided to settle on this block-encryption approach and to
-increasingly expose it to real workloads, we can expect new requirements to
-pop up more frequently and with higher priority. Last but not least, our
-Ada/SPARK runtime, so far, lacks ARM support.
-
-This prospect forced us to carefully reconsider our relation to the existing
-CBE approach, and especially to the fact that its core logic and crypto
-back-end were entirely written in Ada/SPARK. When we started developing the
-CBE in Ada/SPARK, we were positive that the language might become popular
-among the core developers of Genode and that, eventually, other, especially
-critical parts of the framework could benefit from it as well. But this idea
-didn't come to fruition. Only a few of us came in touch with the new language
-and, of those, even fewer acquired profound experience with it. We ultimately
-realized that the friction caused by the added language boundary that emerged
-with the CBE approach became a bottleneck, inhibiting the further evolution of
-our block-encryption stack with a strong sense of collective code ownership.
-
-This observation in mind, and the above-mentioned challenges in sight, we
-decided to drop the CBE library and create a new implementation strongly
-inspired by the CBE design but in C++, our "mother tongue". The new library is
-called tresor, brings the same feature set as the CBE and is compatible with
-containers created with the CBE. The file vault has been adapted to run with
-the tresor library. So file-vault users can continue using their containers as
-usual without further ado. The entire tresor-based ecosystem is
-architecture-agnostic, which lifts the former restriction to x86.
-
-
-File Vault
-~~~~~~~~~~
-
-Some new features have been added to the file vault. For instance, the
-component can now be driven with one of two available user interfaces: The
-usual graphical front-end or the new non-interactive interface that is driven
-by a textual configuration and provides feedback through a report. This allows
-for the integration of the file vault with automated controls respectively
-lower or higher-level UIs. The interactive interface remains the default, but
-one can replace it with the text-based variant using the new "user_interface"
-configuration attribute. An example of operating the text-based interface is
-provided by the new _file_vault_config_report.run_ script.
-
-As another rather small but handy feature, a file vault can now be locked and
-unlocked without having to restart the component. In the locked state, all key
-material is removed from the cryptographic back end and the block-encryption
-driver is shut down. The user is then prompted to provide the correct
-credentials in order to re-establish access to the container.
-
-
-Custom virtual machine monitor on ARM
-=====================================
-
-The
-[https://genode.org/documentation/release-notes/23.02#Interactive_graphical_VMs_on_ARM - previous release], introduced interactive graphical VMs on ARM systems.
-Genode's custom virtual machine monitor was enhanced by VirtIO device models
-for input events and GPU. However, dynamic changes of the virtual GPU's
-framebuffer resolution weren't yet handled by the initial version. With the
-current release, these restrictions got removed. Now, the user is able to
-resize the window of a virtual machine as expected.
-
-
-NetBSD rump kernel on RISC-V
-============================
-
-We have added RISC-V to our port of the
-[https://wiki.netbsd.org/rumpkernel - rump kernel].
-This enables Genode to access commodity file-systems on RISC-V based devices.
-
-
-Strengthened fault tolerance of on-target package management
-============================================================
-
-Genode's way of safely installing and deploying packages on-target - as
-introduced in
-[https://genode.org/documentation/release-notes/18.02#On-target_package_installation_and_deployment - version 18.02] -
-is a corner stone of Sculpt OS. The recent move of Sculpt OS to mobile
-devices, however, revealed a couple of limitations that we address with the
-current release.
-
-First, in contrast to the PC version of Sculpt OS that allows for the
-straight-forward management and editing of files using a regular command-line
-interface, a touch-based user interface as present on the phone is far more
-constrained. Problems that can be solved by manual intervention on the PC
-without second thought can become insurmountable showstoppers on the phone.
-The most prominent problem is recovery from the situation where package
-dependencies remain incomplete due to an interruption of the installation
-process or due to packaging mistakes. On the PC, such a situation can be
-resolved by simply clearing the depot using a single terminal command,
-followed by a reinstall of the package. On the phone, the user was left out in
-the cold with the message "package installed but incomplete" but with no
-obvious or non-obvious way of recovery. The new version gracefully handles
-this failure state by offering the retry of the package installation.
-
-Second, network connectivity is far more fluctuating on mobile devices, which
-increases the likelihood for download errors. The previous version that
-regarded download errors as rare and sporadic issues, responded to such errors
-by repeated and silent retries. We found that a mobile phone demands a more
-graceful way to reflect such failure situations to the user, and to limit the
-rate of futile download attempts. The new version preserves information about
-download failures for user inspection and re-issues new downloads only if not
-already flagged as unavailable.
-
-Finally, we encountered the manual addition of software providers to the
-system as a hurdle on the phone. On the PC, a new software provider can be
-added by manually placing the provider's _download_ and _pubkey_ files in a
-local depot directory, which is straight-forward when using a shell. However,
-on a touch-screen device, there is no obvious and simple way to supplement the
-system with such information. To still accommodate the user's desire to
-download and install software from arbitrary providers, we added the option to
-explicitly skip the signature verification for downloads. This is useful in
-scenarios where the lack of integrity of downloaded content does not pose a
-risk, e.g., for untrusted applications that are rigidly sandboxed, or during
-development.
-
-Whenever the depot-download subsystem encounters the attribute 'verify="no"'
-for an '<installation>' item, it accepts the installation even if no key is
-available. It still applies verification for dependencies whenever possible.
-E.g., if a package of the provider "john" gets installed via 'verify="no"' and
-the package depends on an archive by "genodelabs", for which the public key is
-known, the integrity of the content originating from "genodelabs" is verified.
-
-
-Libraries and applications
-##########################
-
-Qt5 reorganization
-==================
-
-When the Goa tool is used to build an application, all libraries of the used
-API packages get linked to the application and the single Qt5 API package with
-big libraries like QtWebEngine was a bit too much for simple Qt applications.
-For this reason, we split the Qt5 API into smaller packages according to the
-corresponding Qt modules.
-
-As preparation for the release of a binary version of the Qt5 host tools, we
-also reduced the external dependencies of these tools for improved
-compatibility with different host systems and changed their install location
-to the location of the other Genode host tools.
-
-And finally, we added a 'ubuntu-ui-toolkit' meta package in the genode-world
-repository which pulls in all dependencies for the Ubuntu UI toolkit,
-including a runtime with the required ROMs.
-
-
-WireGuard improvements
-======================
-
-There are two smaller changes related to Genode's port of WireGuard. First,
-peers can now be removed from WireGuard at runtime by removing the
-corresponding '<peer>' tags from the component's configuration. This operation
-enforces the same assurances as removing a peer from a native WireGuard driver
-in Linux.
-
-The second change has to do with the nature of the port. The WireGuard port is
-one of the rare examples where we use our Linux device driver environment
-(dde_linux) for porting software that is not exactly a driver. The component
-does not depend on a specific hardware configuration and therefore, the
-emulated Linux kernel can be platform-agnostic. Consequently, while porting,
-we created such a variant of the Linux emulation specifically for WireGuard.
-
-However, we realized that this variant can come in handy for ports of other
-hardware-agnostic kernel parts (for instance, lxip) as well. Therefore, we now
-cut it out of the WireGuard port in order to make it a self-contained version
-of the 'lx_emul' library. The new library is called 'virt_lx_emul' and is
-accompanied by the 'virt_linux' target that can be used to build the
-corresponding Linux kernel and run it in Qemu.
-
-
-Updated or removed 3rd-party software
-=====================================
-
-VirtualBox updated to version 6.1.44
-------------------------------------
-
-Our port of VirtualBox underwent some maintenance work published in this
-release. With the tool chain updated to GCC 12, it became necessary to update
-VirtualBox to version 6.1.44 to keep up with the tool-chain changes and fix
-many upstream bugs alongside. Also, we improved several aspects of the port to
-improve robustness of networking, USB, multi-threading, and VM reboot. After
-thorough testing in every-day scenarios, we finally adopted the handling of
-the x86 time-stamp counter from version 5 and disabled the VM exit for the
-RDTSC instruction, which improves the performance of selected scenarios
-significantly. For Windows guests, it has become crucial to configure the
-paravirtualization provider like follows in the _machine.vbox6_ file.
-Otherwise, the guest's TSC calibration fails resulting in a bogus CPU
-frequency assumption.
-
-! <Paravirt provider="HyperV"/>
-
-
-Removed ports of pcre16 and icu libraries
------------------------------------------
-
-The pcre16 and icu libraries had been used by Qt5 in the past but were not
-used anymore since the last Qt updates. So we removed them from the _libports_
-repository.
-
-
-Device drivers
-##############
-
-Linux device driver environment updated to Linux 6.1.20
-=======================================================
-
-According to [https://genode.org/about/road-map - our roadmap], the update of
-Genode's Linux device driver environment (DDE) to a more recent 6.x Linux
-version was planned for release 23.08. Now, we decided to tackle this update
-with this version already.
-
-Besides the Wireguard port to Genode, the following ported drivers use the
-latest Linux kernel 6.1.20 version now:
-
-* Zynq SD-card driver
-* PCI Wifi driver for i.MX 8MQ
-* all PC drivers (USB host, Wifi, Intel display)
-
-Note that a few drivers are not listed above. The existing drivers for the
-Allwinner and i.MX 8MQ SoC still use older 5.x Linux kernel versions as base.
-However, the Linux device driver environment has been tweaked carefully to
-support a range of Linux kernel versions from 5.11 till 6.1.20.
-
-While doing the update work, we investigated a more sustainable link between
-the Linux kernel drivers for USB and display drivers (DRM/KMS) on the one
-hand, and the Genode API on the other. The outcome is explained in the next
-two sections.
-
-
-Intel display driver
-====================
-
-During the update of DDE Linux to the Linux 6.1.20 version, the dependency on
-internal structures of the Intel framebuffer driver (intel_fbdev) became a
-hassle. Although the update was successful finally, we decided to remove the
-direct usage of intel_fbdev in our ported Intel display driver, in order to
-ease future updates. Nevertheless, the functionality of intel_fbdev is
-required to manage the framebuffer memory to provide a working Genode GUI
-interface by the driver. For that, we investigated the use of the
-[https://www.kernel.org/doc/html/v5.0/gpu/drm-kms.html - Linux DRM/KMS]
-interface, specifically to allocate and manage so called
-[https://www.kernel.org/doc/html/v5.0/gpu/drm-kms.html#dumb-buffer-objects - dumb buffer objects].
-As described in the linked article, the dumb buffers are a standardized and
-streamlined way to make early boot graphics possible driven by user-land
-tools. We adjusted our port along the ioctl's of the dumb buffer functionality
-to manage the framebuffer in our ported display driver.
-
-
-USB
-===
-
-Connecting different USB clients to a USB host controller driver is a delicate
-task. When using a port of a Linux kernel driver, it can quickly become
-brittle because the USB driver API in the Linux kernel is complex and contains
-some semantic dependencies, for instance regarding synchronization, which are
-not always obvious. However, the Linux kernel offers a USB device I/O API to
-the user-land that is used for instance by libusb. This API has to guard the
-USB subsystem against wrong usage, and implements the necessary semantics
-regarding synchronization and dynamic changes of clients and devices. In the
-past, we repeatedly encountered corner-case issues, if clients or devices
-vanished and appeared at a high rate. For the sake of robustness, we decided
-to redesign our internal linking in between the Genode USB API and Linux to
-use the user-level device I/O API of the latter. Moreover, we extended the
-capacity of USB packets in-flight that can be handled by the controller in
-parallel to 32, to enhance the throughput for some USB devices.
-
-
-NVMe storage
-============
-
-Our custom NVMe driver received the following improvements. First we added
-'host-memory-buffer' (HMB) support to the driver, which is a performance
-optimization for NVMe devices that do not make use of a DRAM cache for its
-operational data.
-
-The amount of memory used for the HMB can be set by adding the 'max_hmb_size'
-attribute in the '<config>' node of the driver. This value is checked against
-the constraints imposed by the device. Should the value be less than the
-minimal required amount of memory, it will not be used and a warning is
-issued. On the other hand, if the specified value is larger than the preferred
-amount of memory as favored by the device, it will be capped to the useful
-amount instead.
-
-Naturally, when using the HMB, the required RAM quota of the driver component
-increases by that amount.
-
-Second, we fixed a problem detecting the block size (LBA format) of a given
-namespace. The lower 4 bits of the 'FLABS' register indicate which of the (up
-to) 16 supported LBA formats is used by the namespace. However, instead of
-only making use of those bits, the driver looked at the whole register that
-also includes other information. This led to using the wrong index for reading
-the LBA format and, on certain devices, rendered the driver unusable as the
-assumed block size was detected wrong.
-
-
-Audio-driver update
-===================
-
-We updated the audio driver for HDA devices ported from OpenBSD to version 7.3.
-The functional changes are minimal, but the new version supports more recent
-PC platforms and recognizes more codecs.
-
-
-Platforms
-#########
-
-Base-HW microkernel
-===================
-
-Principle x86 virtualization support (on Qemu)
-----------------------------------------------
-
-This release brings limited support for AMD's Secure Virtual Machine (SVM)
-vCPUs to Genode's custom base-hw microkernel. Supporting SVM is meant as an
-intermediate step towards enabling advanced virtualization workloads using
-VirtualBox on Intel VMX later this year. The approach allows us to craft the
-kernel's virtualization infrastructure using Qemu - which is able to emulate
-SVM in software - and cross-test our implementation against other hypervisors
-in a tightly controlled setting. For reference, we used the time-tested Qemu
-version 4.2 for this line of work.
-
-Implementing principle vCPU support revealed a few points of friction between
-base-hw's kernel interface, which had been designed for the needs of our
-custom ARM VMM, and our kernel-agnostic VM interface on x86 that has been
-carefully crafted to support a range of 3rd party hypervisors, but relies on
-more logic in the kernel-specific VMM library to manage the vCPU state.
-
-The current implementation is able to run several test VM workloads like the
-artificial 'vmm_x86' test, our seoul VMM run scripts with Linux, and - of
-course - Genode VMs on one vCPU. It has thereby reached an important stepping
-stone towards our actual goal of hosting VirtualBox on Intel hardware.
-
-Having shown that base-hw can support the generic x86 VM interface, we will
-mature our implementation and may adapt our interface to make it a better fit
-to base-hw's vCPU execution model in the future.
-
-
-Boot-time RAM detection on the PinePhone
-----------------------------------------
-
-For the PinePhone, we implemented dynamic detection of the system RAM size by
-parsing the values of the DRAM controller as programmed by U-Boot. This way, 2
-and 3 GB models of the PinePhone are supported by Genode.
-
-
-Updated seL4 microkernel
-========================
-
-With this release, we updated the support of the seL4 kernel from 9.0.1 to
-12.1.0 for i.MX6 Sabrelite board and x86_64 PC. The support for 32-bit PC got
-removed since it is unused, and the i.MX7 Sabrelite support got removed since
-it is not supported by the new seL4 kernel anymore.
-
-The updated seL4 kernel requires additional host tools installed, namely
-CMake, Ninja and additional Python3 modules, jinja2, jschonschema, and pyfdt.
-Depending on the distribution, the modules are available as distribution
-package or need to be installed with the python pip3 tool.

doc/release_notes/23-08.txt

@@ -1,786 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 23.08
-              ===============================================
-
-                               Genode Labs
-
-
-
-The headline features of Genode 23.08 are concerned with developer tooling.
-First, we re-approached Genode's GDB debugging support with the grand vision
-of easy on-target debugging directly on Sculpt OS. Our new debug monitor
-introduced in Section [Multi-component debug monitor] combines the GDB
-protocol with Genode's init component. Thereby, the monitor can transparently
-be integrated in Genode subsystems and can be used to debug multiple
-components simultaneously.
-
-Second, the Goa tool, which started as an experiment in 2019, has been shaped
-into an all-encompassing alternative to Genode's traditional work flows for
-developing, porting, and publishing applications. The tool got vastly more
-flexible with respect to runtime testing, and even became able to handle
-dependencies between Goa projects. The massive improvements are covered in
-Section [Goa tool gets usability improvements and depot-index publishing support].
-
-Besides the headline features of the release, we admittedly deviated from the
-original plans laid out on our [http:/about/road-map - road map]. Early-on in
-the release cycle, we found ourselves drawn to code modernization, the
-retiring of legacies, and quality assurance. E.g., we finally updated some of
-the most veteran internals of the framework to our modern-day coding
-practices, we urged to continue the success story of our new Linux
-device-driver environment (DDE) by replacing old USB drivers by new components
-leveraging the modern approach, and created a new DDE-Linux-based NIC driver
-for PC hardware while retiring the aged iPXE-based traditional driver. The
-outcome of this tireless work may hardly be visible from a feature perspective.
-But it greatly improves the velocity and quality of the code to maintain down
-the road.
-
-It goes without saying that the other topics of the road map haven't been
-disregarded. In fact we celebrated a break-through with x86 virtualization
-on our base-hw kernel, are diving deep into the latest Intel platforms, and
-working on the user-visible side of the mobile version of Sculpt OS. But since
-those topics are not wrapped up yet, we all have to stay tuned for the next
-release.
-
-
-Multi-component debug monitor
-#############################
-
-The debugging of Genode components using the GNU debugger (GDB) was already
-an anticipated feature when we introduced the first version of the GDB monitor
-component in version
-[https://genode.org/documentation/release-notes/11.05#GDB_monitor_experiment - 11.05]
-and refined it in the subsequent releases
-[https://genode.org/documentation/release-notes/12.02#GDB_monitor_refinements_and_automated_test - 12.02],
-[https://genode.org/documentation/release-notes/13.11#GNU_Debugger - 13.11] (on-target GDB), and
-[https://genode.org/documentation/release-notes/16.05#Enhanced_GDB_support_on_NOVA - 16.05] (supporting NOVA).
-Despite these efforts, the feature remained rarely used in practice.
-In most situations, manual instrumentation with debug messages or the use
-of GDB with the Linux version of Genode remain to be the instruments of choice.
-Driven by the vision of easy on-target debugging on Sculpt OS, we identified
-the following limitations of the existing GDB monitor that stand in the way.
-
-# The GDB monitor supports only one component as debugging target, which makes
-  the debugging of scenarios where components closely interact difficult.
-
-# The existing implementation re-uses the gdbserver code and thereby inherits
-  many POSIX peculiarities that must be stubbed for Genode, yet make the
-  overall implementation complex. Genode is not POSIX after all.
-
-# The integration of the GDB monitor into an existing scenario is a fairly
-  invasive change that requires too much work.
-
-Given these limitations as a backdrop, two key ideas motivated a new approach
-for the revision of Genode's GDB support for this release:
-
-First, by using Genode's sandbox API as foundation for a new debug monitor,
-we would become able to use the monitor as drop-in replacement for 'init',
-potentially going as far as using the monitor for Sculpt's runtime subsystem.
-Wouldn't that approach vastly simplify the integration issue (3)?
-Second, GDB supports the debugging of multiple processes (called inferiors)
-within one session, which would in principle allow us to inspect and debug
-component compositions, addressing the first limitation.
-And third, the casual review of the documentation of the GDB protocol left
-the impression that a Genode-tailored implementation shouldn't be that
-complicated.
-
-The result of these ideas is the new *monitor* component at _os/src/monitor_
-as the designated successor of the traditional gdb_monitor. By leveraging the
-sandbox API, it can be used as a drop-in replacement for the init component
-and monitor multiple components. In real-world scenarios like Sculpt's
-runtime, we deliberately want/need to restrict the debugging to a few selected
-components, however, which calls for the support of a mix of monitored and
-regular components hosted side by side. Given this requirement, the sandbox
-API had to be enhanced to support the selective interception of PD and CPU
-sessions.
-
-Like the original gdb_monitor, the new monitor speaks the GDB remote serial
-protocol over Genode's terminal session. But the protocol implementation does
-not re-use any gdbserver code, sidestepping the complexities of POSIX.
-The monitor supports the essential GDB remote protocol commands for reading
-and writing of memory and registers, for stopping and resuming of threads
-including single-stepping, and it reports the occurrence of page faults and
-exceptions to GDB. Breakpoints are managed by GDB using software breakpoint
-instructions. The GDB protocol is operated in GDB's 'non-stop' mode, which
-means that threads of multiple inferiors can be stopped and resumed
-individually or in groups, depending on the GDB commands issued by the user.
-
-As of now, the monitor supports NOVA on 64-bit x86 as well as Genode's custom
-base-hw kernel on 64-bit ARM and x86. The 64-bit ARM support required a change
-in Genode's customized GDB port to enable shared-library support for this
-architecture. So in order to use Genode's host GDB with the monitor on 64-bit
-ARM, the Genode tool chain needs to be rebuilt with the _tool/tool_chain_
-script.
-
-There exist three run scripts illustrating the new component. The
-_os/run/monitor.run_ script exercises memory inspection via the 'm' command
-and memory modification via the 'M' command by letting a test program monitor
-itself. The _os/run/monitor_gdb.run_ script performs automated tests of various
-GDB commands and the _os/run/monitor_gdb_interactive.run_ script allows for the
-interactive use of GDB to interact with monitored components.
-
-Details about the configuration of the monitor component are given by the
-README file at the _os/src/monitor/_ directory.
-
-
-Goa tool gets usability improvements and depot-index publishing support
-#######################################################################
-
-Moving the Goa tool under the umbrella of Genode Labs in the previous release
-unleashed a wave of substantial improvements.
-
-Most significantly, we were able to integrate support for depot-index projects
-into Goa (Section [Support of index projects]). This greatly simplifies the
-publishing of user-specific Goa projects for the upcoming Sculpt release.
-
-One of the game-changing features of Goa is its ability to easily test-run
-applications on the host system leveraging Genode's ABI compatibility between
-different kernels. However, in various instances, we still required customized
-runtime scenarios in order to render an application runnable by Goa. With this
-release, we further streamlined Goa's base-linux runtime with Sculpt OS
-(Section [Run-stage generalization]).
-
-Apart from these major changes, the lately added shared-library support and
-Rust support have seen practical improvements.
-
-
-Support of index projects
-=========================
-
-With an increasing number of Genode applications being developed with Goa,
-being able to manage and publish a personal depot index with Goa became due.
-In the past, we needed to build, export, and publish each individual Goa
-project and manually add it to the depot index in order to make it available
-for a particular Sculpt release.
-
-For this purpose, we added support for index projects to Goa. An index project
-is defined by an 'index' file. This file follows the structure of a depot index
-but only names the archive names (lacking depot user and version). The
-'goa export' command augments these names with the current depot user and
-version information. By running 'goa publish', the result is published as a
-depot index for the current Sculpt version.
-
-As Goa supports a hierarchical project structure, an index project may
-contain subdirectories with other Goa projects that provide the corresponding
-pkg archives. The 'goa export' command issued within such an index project
-recursively scans the working directory for any Goa project providing the
-required depot archives or any of their dependencies, and exports these
-subprojects as well.
-
-To make working with index projects an even more joyful experience, we changed
-the way Goa looks up version information. Goa used to expect the current
-version of each required depot archive to be specified in a goarc file. For
-each Goa project, however, a 'version' file may be used to specify the current
-version. This file was only evaluated on export of the particular project.
-With this release, Goa now scans the working directory for Goa subprojects in
-order to look up their 'version' file. This spares us keeping the 'version'
-files and goarc files in sync. The new 'bump-version' command adds another
-level of convenience as it automatically updates the 'version' file of a Goa
-project. In combination with the '-r' switch, we are now able to update the
-version information of all subprojects with a single command.
-
-An example of an index project is found at _examples/index_ in the Goa
-repository.
-
-:Goa tool:
-
-  [https://github.com/genodelabs/goa/]
-
-
-Run-stage generalization
-========================
-
-In addition to building, exporting, and publishing of depot archives, Goa
-supports test-running an application project directly on the development
-system by utilizing base-linux. Similarly to how Goa modularized the build
-stage to support various build systems, we generalized the run stage to pave
-the way for other targets than base-linux. The interface of the generalized
-run stage and the current feature set of the linux target is documented by
-'goa help targets'.
-
-In the course of generalizing the run stage, we introduced various plausibility
-checks to further accelerate application development. For instance, we check
-for typos in required and provided services of a runtime, and verify the
-availability of required ROM modules.
-
-Furthermore, the linux target underwent a major revision to streamline the
-application development for Sculpt OS.
-
-* Scenarios using a terminal component require a fonts file system.
-  In Sculpt OS, this is typically provided by instantiating a fonts_fs
-  component. Doing the same in Goa lifts the need to wrap Goa-managed
-  Sculpt packages in a separate test project.
-
-* A route for the mesa_gpu_drv.lib.so ROM module was implicitly added when
-  a Gpu was required. For consistency with existing packages, we now require
-  the runtime file to mention the mesa_gpu_drv.lib.so ROM explicitly.
-
-* For NIC requirements, we used to take the label as the tap-device name to
-  which the NIC driver was bound. Since the 'label' attribute might be
-  evaluated differently by Sculpt OS, we introduced the 'tap_name' attribute
-  instead. For each distinct tap device, we now instantiate a pair of NIC
-  driver and NIC router. Each router uses a distinct subnet for its default
-  domain, starting at 10.0.10.0/24 and ending at 10.0.255.0/24.
-
-* The clipboard ROM and Report requirements are now routed to a report_rom
-  component.
-
-* Arbitrary ROM requirements are routed to an lx_fs component that provides
-  the files found in the project's _var/rom_ directory as individual ROM
-  modules. An example resides in _examples/external_rom_. Thanks to Pirmin
-  Duss for this useful contribution.
-
-* Remaining service requirements that are not handled otherwise will be routed
-  to a black-hole component.
-
-
-Improved support for building shared libraries
-==============================================
-
-Since release 23.02, we are able to
-[https://genode.org/documentation/release-notes/23.02#Building_and_packaging_CMake-based_shared_libraries__via_Goa_ - build CMake-based shared libraries in Goa].
-In this release, this feature has seen a few improvements:
-
-* If available, Goa now calls 'make install' during build in order to install
-  artifacts into _<build_dir>/install_. For libraries, this typically also
-  installs include files into this directory. Having all include files in the
-  build directory is a prerequisite for extracting these as api artifacts
-  (see 'goa help api').
-
-* We added support for publishing api archives.
-
-* 'goa export' now respects the 'common_var_dir' configuration variable and
-  '--common-var-dir' command-line option when exporting api archives.
-
-* We fixed an issue that resulted in large binaries when building shared
-  libraries with Goa.
-
-
-Quality assurance and usability tweaks
-======================================
-
-Increasing our development efforts for the Goa tool demands means to catch
-regressions early on. For this purpose, we added a basic testing facility,
-which validates that our examples still work as expected. Note that we are
-going to address automated testing for arbitrary Goa projects at some point in
-the future.
-
-With this release, we changed the name of the '.goarc' files to 'goarc'. The
-original intention of these files was to allow user-specific settings
-analogously to, e.g., '.bashrc'. However, these files may contain arbitrary Tcl
-code, thus having various '.goarc' files checked into git repositories, made
-things a little bit too obscure because those files are hidden. When a user
-clones a Git repo and invokes Goa commands, this code gets executed. Hence, it
-is only fair to bring this code to the user's attention by not hiding it.
-
-In addition to all the aforementioned major changes, we added a couple of minor
-usability tweaks:
-
-* We added 'goa help import' in order to document the syntax of the 'import'
-  file.
-
-* We added the 'goa depot-dir' command that allows initializing a custom depot
-  directory with the default depot users.
-
-* We added a 'goa run-dir' command that prepares the run directory without
-  actually running the scenario. This is helpful when the run time of 'goa run'
-  is automatically evaluated by external scripts since 'goa run-dir' may take a
-  while downloading the required depot archives.
-
-* We added the 'run_as' configuration variable and '--run-as' command-line
-  option. This allows changing the depot user from which 'goa run' downloads
-  the required archives. See 'goa help config' for more details.
-
-
-Support for the mainline Rust toolchain
-=======================================
-
-When we reintroduced Rust on Genode in the
-[https://genode.org/documentation/release-notes/23.05#Initial_Rust_support - previous]
-release, our implementation relied on a slightly adapted Rust toolchain to
-work around missing support for versioned library symbols in our linker. With
-this release, we are now able to use the mainline 'x86_64-unknown-freebsd'
-target provided by Rust project, eliminating the need for a custom toolchain.
-
-On top of the streamlined Rust support, we created a Goa package for a popular
-Rust command-line application, which will be published along with updated
-system packages in the upcoming Sculpt release.
-
-For details on the mainline Rust toolchain support and the ported package,
-take a look at the dedicated
-[https://genodians.org/atopia/2023-08-24-enabling-the-upstream-rust-toolchain - blog post on Genodians.org].
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-Internal core and base-framework modernization
-==============================================
-
-Genode's API received multiple rounds of modernization in the past years. But
-some of the framework's deepest internals remained largely unchanged over that
-time. Even though one can argue that mature and battle-tested code should
-better not be disrupted, our programming practices are not carved in stone.
-To make Genode's internal code a delight for reviewers, auditors, and future
-maintainers, we revisited the following areas.
-
-Core's page-fault resolution code got reworked for improved clarity and
-safety, by introducing dedicated result types, reducing the use of basic
-types, choosing expressive names, and fostering constness. Along the way, we
-introduced a number of 'print' hooks that greatly ease manual instrumentation
-and streamlines diagnostic messages printed by core. Those messages no longer
-appear when a user-level page-fault handler is registered for the faulted-at
-region map. So the monitor component produces less noise on the attempt to
-dump non-existing memory.
-
-Closely related to the page-fault handling, we tightened the distinction
-between rx and rwx inside core by restricting 'Region_map::attach_executable'
-to create read-only mappings, while offering the option to map the full rights
-using a new 'attach_rwx' method. The 'attach_rwx' method is now used by the
-dynamic linker to explicitly attach the linker area with full rwx rights. With
-the old page-fault handling code, the execute flag was evaluated only for leaf
-dataspaces, not for managed dataspaces while traversing region-map
-hierarchies. With the new page-fault handling code, the execute bit is
-downgraded to no-execute when passing a managed dataspace that is not attached
-as executable.
-
-We ultimately removed the last traces of the global 'env_deprecated()'
-interface that was still relied-on within core and parts of the base library.
-Nowadays, we no longer use global accessors but generally employ
-dependency-injection patterns. Since the 'env_deprecated()' interface is
-closely related to initialization code, the startup code of core and regular
-components got largely refactored, eliminating the reliance on global side
-effects. As a collateral change, the legacy 'main' support for native Genode
-component as well as the now-obsolete 'Entrypoint::schedule_suspend' mechanism
-got removed.
-
-
-API changes
-===========
-
-Register framework update
--------------------------
-
-The register framework has been updated to ease its use with '-Wconversion'
-warnings enabled, which is the default for Genode components.
-When reading from a bitfield, the new version returns the value in the
-smallest possible integer type, not the register-access type. This way,
-the user of the bitfield value can use appropriate types without the need for
-casting. The update also replaces 'bool' access types with 'uint8_t' access
-types.
-
-Thanks to this change, the net lib - used by Genode's low-level network
-routing components for parsing protocol headers via the register API - has
-been made compliant to strict conversion warnings.
-
-
-Hex-dump utility
-----------------
-
-To aid the monitoring, implementation, and debugging of binary protocols, a
-handy hex-dump utility got added to _util/formatted_output.h_. The new
-'Genode::Hex_dump' class can be used to print a hexadecimal dump of a byte
-range. The data is printed in a format similar to that used by the 'xxd'
-utility. In addition to the 'xxd' format, consecutive duplicate lines are
-replaced with a single "*\n".
-
-
-Libraries and applications
-##########################
-
-New NIC server for raw uplink connectivity
-==========================================
-
-With Genode
-[https://genode.org/documentation/release-notes/21.02#Pluggable_network_device_drivers - 21.02],
-we transitioned all network device drivers to act as session clients in order
-to make them pluggable. We achieved this by introducing a new _uplink_ service
-interface that is very similar to the NIC service but with the peer roles
-switched. Up to now, the only uplink server and uplink-to-NIC adapter was the
-NIC router. This is reasonable as it is the standard network multiplexer in
-Genode and therefore normally sits in front of each network device driver
-anyway. However, there is one major issue with this approach: It binds
-physical network access to layer 3 and 4 routing respectively layer 2
-multiplexing, which, in our case, means that NIC clients can talk to the
-physical network only with what is protocol-wise supported by the NIC router.
-
-That's why Genode 23.08 introduces the new NIC-uplink adapter component. It
-re-enables raw access to physical networks in Genode by forwarding packets
-unmodified and unfiltered between multiple NIC sessions and one uplink
-session. The new component is accompanied by a test script _nic_uplink.run_
-that demonstrates the low-level integration and a Sculpt package _pkg/pc_nic_
-that can be used for deployment in more sophisticated systems together with
-the PC NIC-driver as back end.
-
-One constellation, in which the NIC-uplink server will be especially useful for
-us is the planned enablement of IPv6 on different layers of Genode's network
-stack. More specifically, the tool will allow us to work at IPv6 support in
-both Genode's ported TCP/IP stacks and the NIC router at the same time.
-
-
-New depot-remove component
-==========================
-
-_The work described in this section was contributed by Alice Domage._
-_Thanks for this welcome addition._
-
-Genode's on-target package management allows for the installation of multiple
-versions of the same package side by side, which is useful to roll back the
-system to an earlier state, or to accommodate software depending on an older
-library version. Software is installed into the so-called _depot_ stored on
-the target and populated with downloads on demand. Until now, however, the
-on-target depot could only grow, not shrink. Even though this limitation
-hasn't been a pressing concern for Sculpt OS on the PC, it impeded embedded
-use cases.
-
-The new depot-remove component lifts this limitation by providing an orderly
-way to remove depot content and orphaned dependencies. It operates by reading
-its configuration and processes delete operations based on the provided rules.
-A typical configuration looks as follows.
-
-! <config arch="x86_64" report="yes">
-!     <remove user="alice" pkg="nano3d"/>
-!     <remove user="bob"   pkg="wm" version="2042-42-42"/>
-!     <remove-all>
-!         <keep user="alice" pkg="fonts_fs"/>
-!     </remove-all>
-! </config>
-
-For more details about the configuration options, please refer to the README
-file at _/gems/src/app/depot_remove/_. Furthermore, the
-_gems/run/depot_remove.run_ script illustrates the component by exercising
-several practical use cases.
-
-
-DDE-Linux changes
-=================
-
-With this release, we changed how external events are treated within the
-Linux emulation environment.
-
-Whenever an external event occurred, for example timer or interrupt, the
-corresponding I/O signal handler was triggered. This handler unblocked the
-task waiting for the event and also initiated the immediate execution of all
-unblocked tasks. This, however, could lead to nested execution because these
-tasks might hit serialization points, e.g., synchronously waiting for packet
-stream operations, that under the hood also require handling of other I/O
-signals. Such an execution model is not supported and confusing as it mixes
-application and I/O level signal handling.
-
-So the flagging of the scheduling intent is now decoupled from its execution by
-using an application-level signal handler that is run in the context of the
-component's main entrypoint. The I/O signal handler now triggers the scheduling
-execution by sending a local signal to the EP and only flags the occurrence
-of the external event by unblocking the corresponding task.
-In this context, we reworked the interrupt handling itself. Previously all
-interrupts were immediately processed in the I/O signal handler and only the
-currently pending one was handled. Due to the decoupling change the occurrence
-of interrupts becomes merely flagging a state and requires recording all
-interrupts and dispatch them consecutively in one go.
-
-To facilitate this convention, the Lx_kit initialization function got extended,
-and it is now necessary to pass in a signal handler that is used to perform the
-normally occurring scheduler execution. As this signal handler is part of
-the main object of the DDE-Linux based component it is the natural place to
-perform any additional steps that are required by the component before or after
-executing the scheduler.
-
-As it is sometimes necessary to execute a pending schedule from the EP directly,
-in case the scheduler is called from within an RPC function, the scheduler is
-extended with the 'execute' member function that performs the check that the
-scheduler is called from within the EP and triggers the execution afterwards.
-
-
-Tresor block encryptor
-======================
-
-Following the introduction of the tresor library in the
-[https://genode.org/documentation/release-notes/23.05#Revision_of_Genode_s_custom_block-encryption_infrastructure - previous]
-release, we further polished the tresor tester in order to make it run on a
-broad spectrum of target platforms. For instance, the test can now be run
-without entropy input (permanently warning the user about the security risk)
-because some of our test hardware lacks support for it. Besides that, we
-mainly worked at the resource consumption of the test - made it more adaptable
-or reduced it through improvements. This pleased not only less powerful
-hardware but our test management as well.
-
-Furthermore, we fixed a significant former deficiency with the tresor library.
-The library used to work on the raw on-disc data without decoding first. This
-worked fine for some platforms but caused alignment faults on others. That
-said, the tresor library now always decodes into naturally typed and aligned
-C++ structs before accessing the data.
-
-
-Device drivers
-##############
-
-Intel GPU
-=========
-
-The handling of GPUs is somewhat special within the driver world. A GPU is a
-standalone execution unit that can be programmed much like a CPU. In the past,
-there were fixed function GPUs, which have been gradually replaced by
-dynamically programmable units that execute compiled machine code (think
-shader compilers like GLSL or general purpose computing like CUDA or OpenCL).
-This leads to a situation where a GPU driver cannot trust the client that
-sends its machine code to be executed by the GPU. There exists no sufficient
-way of inspecting the compiled machine code for malicious behavior by the GPU
-driver. Therefore, the only reasonable solution for a GPU driver is to send
-the code to the GPU and hope for the best. In case the code execution is not
-successful, GPUs tend to just hang and the only thing a driver can do is to
-make sure via an IOMMU that the code does not access arbitrary memory and
-program a watchdog timer and reset the GPU to a graceful state in case there
-is no proper response. With the current Genode release, we have implemented
-this behavior for GEN9 (HD graphics) and GEN12 (Intel Iris Xe).
-
-
-Intel display
-=============
-
-The ported Linux Intel display driver now supports USB Type-C connectors as
-used with modern notebooks.
-
-
-New PC network driver based on DDE-Linux
-========================================
-
-Since 2010, we use Ethernet drivers ported from the iPXE project in a tiny
-emulation layer on Genode. While those drivers did a good job for the common
-cases, they always had some rough edges that may not hurt in the original
-network-booting use case but had become a nuisance in Sculpt OS and Genode
-in general. Most prominently the dropped link speed with Intel E1000e cards
-on cable unplug/plug and the moderate throughput on GBit links had to be
-addressed.
-
-Our new DDE Linux approach introduced this year makes the porting of drivers
-from the Linux kernel much easier and less labour-intensive as in the past.
-Also, Linux is a very tempting Ethernet driver donor because of the variety
-of supported devices and the well known excellent performance (especially on
-Intel devices). Moreover, the Intel E1000e driver addresses all issues we
-had with the iPXE implementation and promises a smooth interplay with Intel
-AMT/ME. Note, Intel AMT Serial-over-LAN is still an important debug console
-while deploying Genode on Intel-based notebooks.
-
-Hence, the current release brings the new _pc_nic_drv_ for Intel e1000/e1000e,
-Realtek 8169, and AMD PCnet32 (Qemu) devices on PC and is fully integrated
-into Sculpt OS. Performance-wise the driver easily saturates 1 GBit links in
-our throughput tests.
-
-
-USB host controller
-===================
-
-The USB host controller driver ports for Raspberry Pi 1 and i.MX 6 Quad got
-updated to Linux kernel version 6.1.37 resp. 6.1.20. Both driver ports share
-the renewed device-driver environment approach for Linux introduced in release
-[https://genode.org/documentation/release-notes/21.08#Linux-device-driver_environment_re-imagined - 21.08].
-
-Besides the update of the last remaining outdated USB host controller drivers,
-we have reworked the common C/C++ Linux-to-Genode USB back end used by all USB
-host controller driver incarnations. The internal changes were necessary to
-address issues regarding races during USB session close attempts, resets of
-USB endpoints, and potential stalls during synchronous USB RPC calls.
-
-
-PC audio refinements
-====================
-
-In this release, we simplified the memory allocator in the OpenBSD-based
-audio-driver component and thereby decreased its memory usage. The memory
-subsystem implementation was initially brought over from DDE Linux and is
-geared towards use cases where a high-performing allocator is desired. For the
-audio driver with its clear memory usage pattern, such an allocator is not
-necessary and since no other driver that could benefit from it was ported in
-the meantime, we opted for replacing the implementation with a simpler one
-with less overhead.
-
-We also adapted the mixer state report mechanism to always generate a new
-report on head-phone jack sense events.
-
-Furthermore, we decreased the internal buffer size to implicitly limit the
-number of blocks provisioned for recording that brings them in line with the
-number of blocks used for playback (2).
-
-
-Wifi
-====
-
-With the [DDE-Linux changes] in place, we had to adapt the initialization
-procedure in the wireless LAN driver since it behaves differently to all other
-DDE-Linux-based driver components. The driver is actually a 'Libc::Component'
-due to its incorporation of the 'wpa_spplicant' application and the driver
-itself is confined to its own shared-object to better separate the Linux code.
-
-Since we implement the Linux initcalls as static constructors, we have to
-initialize the Lx_kit before those are executed. This is normally not a
-problem because they are executed manually from within the drivers main object
-on construction. However, in a 'Libc::Component' this happens before our main
-object is constructed. In the past, we used a VFS plugin to perform the
-initialization - as the VFS is also constructed beforehand - but this is no
-longer possible as the driver's main signal handler that now dispatches the
-Lx_kit event signals is not available at this point.
-
-We decided therefore to perform a multi-staged boot-up process where the
-component is now implemented as regular 'Genode::Component' that triggers the
-'Libc::Component' construction manually after performing the Lx_kit
-initialization. This change enabled us to remove the VFS 'wifi' plugin that no
-longer has to be specified in the VFS configuration.
-
-Furthermore, we removed the handcrafted MAC address reporter in favor of the
-Genode C API utility that was recently made available.
-
-
-PinePhone support for buttons and screensaver
-=============================================
-
-To equip the mobile version of Sculpt OS on the PinePhone with a proper
-screensaver, we added drivers for detecting user interactions with the
-PinePhone's physical buttons, namely the volume buttons and the power button.
-
-The volume buttons are connected via cascaded resistors to a single ADC of the
-A64 SoC. The corresponding driver has been added to the genode-allwinner
-repository at _src/drivers/button/pinephone/_ and is accompanied by the
-_button_pinephone.run_ script. It reports KEY_VOLUMEUP and KEY_VOLUMEDOWN
-input events to an event session.
-
-Sensing the power button has been a slightly more delicate issue because the
-power button is connected to the power-management IC (PMIC), which shall only
-be accessed via the system-control processor (SCP). To detect state changes,
-the PMIC's IRQ (routed through the R_INTC to the GIC) is now handled by the
-power driver. This has the added benefit that also other interesting PMIC
-events (like connecting AC) get immediately reported.
-
-With the button drivers in place, we finally equipped Sculpt OS with a
-screensaver as a crucial battery-conserving feature. The screensaver kicks in
-after the user remained inactive in the administrative user interface for some
-time. It also can be manually activated by pressing the power button. While
-the screen is blanked, a press of the power button enables the display again.
-
-Under the hood, Sculpt completely removes the drivers for the display and the
-touchscreen while the screen is blanked, which considerably reduces the power
-draw. The system also switches the CPU to economic mode while the screen is
-blanked. Here are some illustrative data points:
-
-!    Max brightness in performance mode: 2.8 W
-!    Max brightness in economic mode:    2.6 W
-!    Low brightness in economic mode:    1.7 W
-!    Screensaver:                        1.1 W
-
-You can find the screensaver feature integrated in the latest mobile Sculpt OS
-images published by _nfeske_.
-
-
-Platforms
-#########
-
-NXP i.MX SoC family
-===================
-
-Certain parts of i.MX specific code, like the base support for the hw kernel,
-and the GPIO driver for i.MX got moved from Genode's main repository to the
-corresponding genode-imx repository.
-
-Sculpt OS image creation for MNT Reform2
-----------------------------------------
-
-With this release, we introduce mainline support for Sculpt OS on the MNT
-Reform2. To build a Sculpt OS image for this board you can use the common
-_gems/run/sculpt_image.run_ script, like the following:
-
-! make run/sculpt_image KERNEL=hw BOARD=mnt_reform2 DEPOT=omit
-
-To be effective, you need to extend your RUN_OPT variable accordingly:
-
-! RUN_OPT += --include image/imx8mq_mmc
-
-
-seL4 microkernel
-================
-
-With the update of the seL4 kernel in the
-[https://genode.org/documentation/release-notes/23.05#Updated_seL4_microkernel - previous]
-release we now added several improvements, which reduce the boot-up time of
-Genode's 'core' roottask on seL4 by converting untyped memory to I/O memory on
-demand.
-
-
-Build system and tools
-######################
-
-Depot autopilot on-target test orchestrator
-===========================================
-
-As the rough plan to support automated testing in Goa is shaping up, it makes
-sense to share one convention about expressing the success criteria for a
-package under test between the depot autopilot and Goa. This prospect motivated
-us to review the convention that was used with the depot autopilot up until
-now. The old syntax looked as follows:
-
-! <runtime ...>
-!   <events>
-!     <timeout meaning="failed" sec="20"/>
-!     <log meaning="succeeded">
-!       [init -> rom_logger] ROM 'generated':*
-!       [init -> dynamic_rom] xray: change (finished)
-!     </log>
-!     <log meaning="succeeded">child exited</log>
-!     <log meaning="failed">Error: </log>
-!   </events>
-!   ...
-! </runtime>
-
-We applied the following simplifications to this syntax:
-* Dropped the intermediate '<events>' tag,
-* Replaced '<log meaning="succeeded">' by '<succeed>',
-* Replaced '<log meaning="failed">' by '<fail>',
-* Replaced '<timeout meaning="failed" sec="20"/>' by an 'after_seconds'
-  attribute of the '<succeed>' or '<fail>' tags.
-
-So, the above example becomes the following:
-! <runtime ...>
-!   <fail after_seconds="20"/>
-!   <succeed>
-!     [init -> rom_logger] ROM 'generated':*
-!     [init -> dynamic_rom] xray: change (finished)
-!   </succeed>
-!   <succeed>child exited</succeed>
-!   <fail>Error: </fail>
-!   ...
-! </runtime>
-
-For now, the depot autopilot maintains backwards-compatibility to allow Genode
-users to adapt to the change progressively. The old scheme is used whenever
-the package runtime contains an '<event>' tag. Note that backwards
-compatibility will be removed after a short transition period.
-All test packages of the official Genode repositories have been updated
-to the new convention.
-
-Furthermore, we took the opportunity to also add a new feature. The optional
-'log_prefix' attribute in the '<succeed>' and '<fail>' tags is a simple but
-handy white-list filter when it comes to typical Genode logs. When matching
-the test log against the pattern given in the affected '<succeed>' or '<fail>'
-tag, the depot autopilot considers only those log lines that start with the
-given prefix. This is an easy way to watch only specific Genode components and
-solve problems with the log order of simultaneously running components.
-
-Last but not least, the transition prompted us to fix a minor issue with the
-depot autopilot log-processing. Color sequences will now be forwarded correctly
-from the test runtime to the log output of the depot autopilot, making the
-analysis of test batteries a more pleasant experience.
-
-
-Updated run-tool defaults for x86_64
-====================================
-
-With the update of the seL4 kernel and the update of the toolchain to GNU GCC
-12 in the previous release, certain x86 assembly instructions like POPCNT are
-generated, which are not supported by the Qemu CPU models we used.
-Previously, the used CPU model was either the default model, or
-'-cpu core2duo' for NOVA, or '-cpu phenom' for SVM virtualization.
-The current release changes the default model to '-cpu Nehalem-v2', and
-selects '-cpu EPYC' for SVM virtualization.
-
-Note that the _build.conf_ file in the x86 build directory must be
-re-generated by you, which otherwise may contain an older Qemu "-cpu " model,
-which can collide with the new default Qemu CPU settings.

doc/release_notes/23-11.txt

@@ -1,799 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 23.11
-              ===============================================
-
-                               Genode Labs
-
-
-
-Genode 23.11 brings a healthy mix of OS architectural work, curation of the
-existing framework, and new features. In an arguably radical move - but in
-perfect alignment with microkernel philosophy - we move the IOMMU driver from
-the kernel to user space. This way, Genode attains DMA protection independent
-of the used kernel. Section [Kernel-agnostic DMA protection] covers the
-background and implementation of this novel approach.
-
-We constantly re-evaluate our existing code base for opportunities of curation
-and simplification and the current release is no exception. It bears the fruit
-of an intense one-year cross-examination of Genode's existing virtualization
-interfaces across CPU architectures and kernels, as a collateral effort of
-bringing x86 virtualization to our custom base-hw microkernel. Section
-[Modernized virtualization interface] presents the story and outcome of this
-deep dive.
-
-As another curation effort, the release brings Genode's arsenal of USB device
-drivers in line with our modern DDE Linux porting approach.
-Section [USB device drivers updated to Linux 6.1.20] details this line of work.
-
-Feature-wise, the release contains the underpinnings of the CPU
-frequency/temperature/power monitoring and control feature of the latest
-Sculpt OS release
-(Section [PC power, frequency, temperature sensing and control]),
-showcases the port of the Linphone VoIP stack using the Goa tool
-(Section [Ported 3rd-party software]), and equips the Seoul virtual machine
-monitor with the ability to host 64-bit guests
-(Section [Seoul virtual machine monitor]).
-
-
-Kernel-agnostic DMA protection
-##############################
-
-On our quest towards a PC version of Sculpt OS on our custom (base-hw)
-microkernel, we were able to move an essential chunk away to clear another
-section of the path. Based on the preparatory changes to the platform driver
-regarding IOMMU handling introduced in
-[https://genode.org/documentation/release-notes/23.05#Towards_kernel-agnostic_DMA_protection - release 23.05],
-we were able to enable kernel-agnostic DMA protection on Intel platforms.
-
-Similar to how the MMU protects the system against unintended CPU-initiated
-memory transactions, the IOMMU protects the system against unintended DMA
-transactions. Since components allocate DMA buffers via the platform driver,
-the latter sits in the perfect spot to manage DMA remapping tables for its
-clients and let the IOMMU know about them.
-
-[image dma_remap]
-
-The figure above illustrates how we added remapping to the PC version of
-Sculpt OS. IOMMUs are announced in the ACPI DMAR table, which is parsed by our
-ACPI driver component.
-It particularly evaluates the _DMA Remapping Hardware Unit Defintions_ (DRHDs)
-and _Reserved Memory Region Reporting_ (RMRRs) structures and reports the
-essential details in form of an _acpi_ report. There are typically multiple
-DRHDs with different device scopes. The RMRRs specify memory regions that may
-be DMA targets for certain devices.
-
-The _acpi_ report is used by our PCI decode component, which creates a
-_devices_ report. It adds the DRHDs as devices to this report and annotates
-the found PCI devices with corresponding '<io_mmu name="drhdX"/>' nodes
-according to the DRHDs' device scopes. Moreover, it adds
-'<reserved_memory .../>' nodes to the particular devices as specified by the
-RMRRs.
-
-By evaluating the _devices_ report, the platform driver has a complete picture
-of the DMA remapping hardware units and knows about which PCI devices fall
-into their scopes. It takes control over the mentioned _drhdX_ devices on its
-own and sets up the necessary structures that are shared between all sessions
-and devices. For every Platform session and _drhdX_ device used, it creates an
-'Io_mmu::Domain' object that comprises a DMA remapping table. As shown in the
-figure, Client A, which acquires devices in the scope of drhd0 and drhd1, the
-platform driver sets up two DMA remapping tables. The tables are populated with
-the DMA buffers allocated via Client A's platform session. For every acquired
-device, the platform driver maps the corresponding remapping table. Note that
-DMA buffers are allocated on a per-session basis so that all devices in the
-same session will get access to all DMA buffers. To further restrict this,
-Client A could open separate platform sessions for distinct DMA-capable
-devices.
-
-A subtle implementation detail (not shown in the figure) concerns the
-aforementioned reserved memory. The reserved memory regions of a device must
-be added to the corresponding DMA remapping table. Moreover, these regions
-must be accessible at all times, i.e. even before the device is acquired by
-any client. For this purpose, the platform driver creates a default remapping
-table. This table is filled with the reserved memory regions and mapped for
-every unused device that requires access to any reserved memory region.
-
-A particular benefit of moving DMA remapping into the platform driver (apart
-from becoming kernel-agnostic) is that DMA remapping tables are now properly
-allocated from the session's quota. In consequence, this may increase the RAM
-and capability requirements for certain drivers.
-
-The platform driver's support for Intel IOMMUs is enabled by default on the
-NOVA and base-hw kernels. The seL4 and Fiasco.OC kernels are not yet covered.
-Nevertheless, we also kept NOVA's IOMMU enablement intact for the following
-reasons:
-
-* To protect the boot-up process from DMA attacks, the IOMMU should be enabled
-  as early as possible. The platform driver simply takes over control when it
-  is ready.
-
-* The platform driver is not (yet) able to manage interrupt remapping because
-  this requires access to the _I/O Advanced Programmable Interrupt Controller_
-  (IOAPIC) controlled by the kernel. Thus, in this release, we still let NOVA
-  manage the interrupt remapping table.
-
-* As we have not implemented support for AMD IOMMUs yet, we simply keep NOVA
-  in charge of this. If there is no Intel IOMMU present, the platform driver
-  falls back to the device PD for controlling the kernel-managed IOMMU.
-
-Along with the DMA remapping support, we added an _iommu_ report to the
-platform driver. On the PC version of Sculpt OS, this is enabled by default
-and routed to _/report/drivers/iommu_. The report summarizes the state of each
-DRHD. When the platform driver takes control, it also logs a message like
-"enabled IOMMU drhd0 with default mappings". The platform driver can be
-prevented from touching the IOMMU by removing the DRHD info from the _acpi_
-report. This can be achieved by supplying the ACPI driver with the following
-config:
-
-! <config ignore_drhd="yes"/>
-
-_Note that the ACPI driver does not handle configuration updates._
-
-Orthogonal to the DMA remapping support, we changed the allocation policy for
-DMA buffers in the generic part of the platform driver. The new policy leaves
-an unmapped page (guard page) between DMA buffers in the virtual I/O memory
-space. This ensures that a simple DMA buffer overflow does not corrupt other
-DMA buffers. Since this is only a matter of virtual address allocation, it
-does not add any additional RAM costs.
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-PC power, frequency, temperature sensing and control
-====================================================
-
-PC CPU vendors provide various CPU features for the operating system to
-influence frequency and power consumption, like Intel HWP or AMD pstate to
-name just two of them. Some of the features require access to various MSR CPU
-registers, which can solely be accessed by privileged rdmsr and wrmsr
-instructions.
-
-Up to now, this feature was provided in a static manner, namely before Genode
-boots. It was possible to set a fixed desired target power consumption via the
-pre-boot chain loader bender. This feature got introduced with
-[https://genode.org/documentation/release-notes/20.11#Hardware_P-State_support_on_PC_hardware - Genode version 20.11]
-and was refined in
-[https://genode.org/documentation/release-notes/22.11#Configurable_Intel_HWP_mode - version 22.11].
-
-Another and desired approach is to permit the adjustment of the desired power
-consumption depending on the current load of the system. This dynamic way of
-power and frequency management has been in casual development since 2021 and
-first got presented in one [https://genodians.org/alex-ab/2023-05-29-freq_power - sneak peak]
-Genodian article. The feature now found its way into the
-[https://genodians.org/alex-ab/2023-10-23-msr - Sculpt 23.10] release.
-
-With the current Genode release, we have added general support to the
-framework that permits guarded access to selected MSRs via Genode's
-system-control RPC of the protection domain (PD) session. If the underlying
-kernel supports this feature, presently the NOVA kernel, read and write
-requests are forwarded via Genode's 'core' roottask to the kernel. A component
-needs the explicit [https://genode.org/documentation/release-notes/22.02#Restricting_physical_memory_information_to_device_drivers_only - managing_system] configuration role to get
-access to this functionality, which is denied by default.
-
-The actual knowledge about how to manage Intel HWP and AMD pstate is provided
-as a native Genode component, which uses the new 'Pd::system_control'
-interface. The component monitors and reports changes of MSR registers for
-temperature (Intel), frequency (AMD & Intel), and power consumption (Intel
-RAPL). Additionally, it can be instructed - by the means of configuration
-changes - to write some of the registers. Besides the low-level MSR component,
-a Genode package with a GUI component is provided to make the interactive
-usage of the feature more user-friendly. For Sculpt, we added an interactive
-dialog to assign the system-control role to a component like the graphical MSR
-package via the resource dialog. For a more detailed description please refer
-to our [https://genodians.org/alex-ab/2023-10-23-msr - Genodians article]
-for the Sculpt 23.10 release.
-
-
-Modernized virtualization interface
-===================================
-
-When we introduced the
-[https://genode.org/documentation/release-notes/19.05#Kernel-agnostic_virtual-machine_monitors - generic Virtual Machine Monitor (VMM) interface]
-for x86 virtualization with Genode
-[https://genode.org/documentation/release-notes/19.05#Kernel-agnostic_virtual-machine_monitors - version 19.05],
-it was largely modeled after our Genode VMM API for ARM with the following
-characteristics.
-
-* A vCPU's state could be requested, evaluated, and modified with the
-  'state()' method.
-
-* The vCPU was started by the 'run()' method.
-
-* For synchronization, the vCPU could be stopped with the 'pause()' method.
-
-However, this ostensibly uniform interface for ARM and x86 virtualization
-obscures two significant differences between the architectures.
-
-:Hardware and generic vCPU state:
-
-On ARM, the VMM directly handles the hardware virtualization state, i.e., the
-vCPU state is directly passed to the VMM. In contrast, what is passed to the
-VMM on x86 is a generic _Vcpu_state_. This is due to two aspects of x86
-virtualization: First, there are two competing implementations of
-virtualization on x86: AMD's _Secure Virtual Machine (SVM)_ / _AMD-V_ and
-Intel's _Virtual Machine Extensions (VMX)_. Second, neither interface lends
-itself to passing the vCPU state directly to the VMM: VMX requires privileged
-instructions to access fields in the _Virtual Machine Control Structure
-(VMCS)_. Whereas SVM supports direct access to fields in its _Virtual Machine
-Control Block (VMCB)_, the VMCB (as well as the VMCS) does not represent the
-whole state of the vCPU. Notably, both the VMCS and the VMCB do not include
-the CPU's general purpose registers, thereby warranting a separate data
-structure to synchronize the vCPU state with a VMM.
-
-:vCPU pause and state synchronization:
-
-On ARM, the 'pause()' method simply stopped the vCPU kernel thread from being
-scheduled. Since the VMM's vCPU handler runs on the same CPU core we could be
-certain that the vCPU was not running while the VMM's vCPU handler was
-executing, and calling 'pause()' made sure the vCPU wasn't rescheduled while
-the VMM was modifying its state. In contrast, calling 'pause()' on x86 has
-different semantics. It requests a synchronization point from the hypervisor,
-which responds by issuing a generic _PAUSE_ or _RECALL_ exit in order to
-signal the VMM that state can be injected into the vCPU. The mechanism is
-woven deeply into the device models of our x86 VMMs, and therefore
-asynchronous state synchronization from the VMM needed to be available in the
-VMM.
-
-
-API shortcomings and improvements
----------------------------------
-
-On ARM, making the hardware vCPU state unconditionally available to the VMM via
-the 'state()' method meant that the API did not enforce any synchronization
-between hypervisor / hardware and VMM accesses to the vCPU state. On x86, the
-asynchronous semantics of the 'pause()' method required complex state tracking
-on the hypervisor side of the interface.
-
-To address both shortcomings, we replaced the previous API with a single
-'with_state()' method that takes a lambda function as an argument. The method
-allows scoped access to the vCPU's state and ensures that the vCPU is stopped
-before calling the supplied lambda function with the vCPU as parameter. Only
-if the lambda function returns 'true', the vCPU is resumed with its state
-updated by the VMM. Otherwise, the vCPU remains stopped.
-
-As a result, the API enforces that the vCPU state is only accessed while the
-vCPU is not running. Moreover, we were able to replace the ambiguous 'pause()'
-method by a generic mechanism that unblocks the vCPU handler, which in turn
-uses the 'with_state()' method to update the vCPU state. Finally, resuming of
-the vCPU is controlled by the return value of the lambda function exclusively
-and, thus, removes the error-prone explicit 'run()' method.
-
-
-Porting hypervisors and VMMs
-----------------------------
-
-The new API was first implemented for *base-hw*'s using AMD's SVM
-virtualization method and recently
-[https://genode.org/documentation/release-notes/23.05#Base-HW_microkernel - introduced]
-as part of the 23.05 release. The reduction of complexity was significant:
-explicitly requesting the vCPU state via 'with_state()' did away with a vast
-amount of vCPU-state tracking in the kernel. Instead, the VMM library
-explicitly requests updates to the vCPU state.
-
-With the first hypervisor ported, we were curious to see how easily our new
-interface could be applied to the *NOVA* hypervisor. The initial pleasant
-reduction of complex state handling in base-nova's VMM library was closely
-followed by the insight that there was no way to match the NOVA-specific
-execution model to our new library interface. The asynchronous nature of the
-'with_state()' interface meant that we needed a way to synchronize the vCPU
-state with the VMM that could be initiated from the VMM. Since NOVA's
-execution model is based on the hypervisor calling into the VMM on VM exits,
-we had to extend NOVA's system call interface to allow for an explicit setting
-and getting of the vCPU state. This was needed because the 'with_state()'
-interface requires that the vCPU state is made available to the caller within
-the method call, so the old model of requesting a _RECALL_ exit that would be
-processed asynchronously couldn't be used here. For the same reason, the vCPU
-exit reason had to be passed with the rest of the vCPU state in the UTCB since
-in this case this information wasn't provided through the VMM portal called
-from the hypervisor. The new 'ec_ctrl' system call variants proved to be a
-simple addition and allowed us to adapt to the new interface while still using
-NOVA's execution model for processing regular exits.
-
-The _blocking system call into the hypervisor_ execution model of *Fiasco.OC*
-and *seL4* offered its own unique set of challenges to the new library
-interface in the interplay between asynchronous 'with_state()' triggers and
-the synchronous vCPU run loop. Fortunately, we were able to meet these
-challenges without changing the kernels.
-
-While adapting our VMMs for ARM and x86, we found varying degrees of
-dependency on permanently accessible vCPU state, which we resolved by
-refactoring the implementations. As a result, the new interface is already
-used since the release of
-[https://genode.org/documentation/articles/sculpt-23-10 - Sculpt OS 23.10].
-We haven't experienced any runtime vCPU state access violations and can now be
-certain that there aren't any silent concurrent accesses to the vCPU state.
-
-All in all, the new VMM library interface has succeeded in reducing complexity
-while providing a more robust access to the vCPU state, which is shared
-between our various hypervisors and VMMs.
-
-
-Dialog API for low-complexity interactive applications
-======================================================
-
-Since version
-[https://genode.org/documentation/release-notes/14.11#New_menu_view_application - 14.11],
-Genode features a custom UI widget renderer in the form of a stand-alone
-component called _menu view_. It was designated for use cases where the
-complexity of commodity GUI tool kits like Qt is unwanted. Menu-view-based
-applications merely consume hover reports and produce dialog descriptions as
-XML. In contrast to GUI toolkit libraries, the widget rendering happens
-outside the address space of the application.
-
-Today, this custom widget renderer is used by a number of simple interactive
-Genode applications, the most prominent being the administrative user
-interface of Sculpt OS. Other examples are the touch keyboard, file vault,
-text area, and interactive
-[https://genodians.org/alex-ab/2023-10-23-msr - system monitoring tools].
-
-In each application, the XML processing used to be implemented via a rather
-ad-hoc-designed set of utilities. These utilities and patterns started to get
-in the way when applications become more complex - as we experienced while
-crafting the
-[https://genodians.org/nfeske/2023-01-05-mobile-user-interface - mobile variant]
-of Sculpt OS. These observations prompted us to formalize the implementation
-of menu-view based applications through a new light-weight framework called
-dialog API. The key ideas are as follows.
-
-First, applications are to be relieved from the technicalities of driving a
-sandboxed menu-view component, or the distinction of touch from pointer-based
-input, or the hovering of GUI elements. These concerns are to be covered by
-a runtime library. The application developer can thereby focus solely on the
-application logic, the UI representation (view) of its internal state (model),
-and the response to user interaction (controller).
-
-Second, the dialog API promotes an immediate translation of the application's
-internal state to its UI representation without the need to create an object
-for each GUI element. The application merely provides a 'view' (const) method
-that is tasked to generate a view of the application's state. This approach
-yields itself to the realization of dynamic user interfaces needing dynamic
-memory allocation inside the application.
-The 'view' method operates on a so-called 'Scope', which loosely corresponds
-to Genode's 'Xml_generator', but it expresses the generated structure using
-C++ types, not strings. A scope can host sub scopes similar to how an XML node
-can host child nodes. Hence, the _view_ method expresses the application's
-view as a composition of scopes such as frames, labels, vbox, or hbox.
-
-Third, user interaction is induced into the application by three callbacks
-'click', 'clack', and 'drag', each taking a location as argument. The location
-is not merely a position but entails the structural location of the user
-interaction within the dialog. For interpreting of the location, the
-application uses the same C++ types as for generating the view. Hence, the C++
-type system is leveraged to attain the consistency between the view and the
-controller, so to speak.
-
-Fourth, structural UI patterns - made out of nested scopes - can be combined
-into reusable building blocks called widgets. In contrast to scopes, widgets
-can have state. Widgets can host other widgets, and thereby allow for the
-implementation of higher-level GUI parts out of lower-level elements.
-
-The API resides at _gems/include/dialog/_ and is accompanied by the dialog
-library that implements the runtime needed for the interplay with the
-menu-view widget renderer. Note that it is specifically designed for the needs
-of Sculpt's UI and similar bare-bones utilities. It is not intended to become
-a desktop-grade general-purpose widget set. For example, complex topics like
-multi-language support are decidedly out of scope. During the release cycle,
-the administrative user interface of Sculpt OS - for both the desktop and
-mobile variants - has been converted to the new API. Also, the text-area
-application and the touch keyboard are using the new API now.
-
-Given that the new API has been confronted with the variety of use cases found
-in Sculpt's administrative user interface, it can now be considered for other
-basic applications. Since we target Genode-internal use for now, proper
-documentation is still missing. However, for the curious, an illustrative
-example can be found at _gems/src/test/dialog/_ accompanied by a corresponding
-_dialog.run_ script. For a real-world application, you may consider studying
-the _app/sculpt_manager/view/_ sub directory of the gems repository.
-
-
-API changes
-===========
-
-Simplified list-model utility
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The so-called 'List_model' utility located at _base/include/list_model.h_ has
-become an established pattern used by Genode components that need to maintain
-an internal data model for XML input data. It is particularly useful whenever
-XML data changes over time, in particular when reconfiguring a component at
-runtime.
-
-The original utility as introduced in version
-[https://genode.org/documentation/release-notes/18.02#API_changes - 18.02]
-relied on a policy-based programming pattern, which is more ceremonial than it
-needs to be, especially with recent versions of C++. The current release
-replaces the original policy-based 'update_from_xml' by a new method that
-takes three functors for creating, destroying, and updating elements as
-arguments. XML nodes are associated with their corresponding internal data
-models by annotating the element type with the 'type_matches' class function
-and the 'matches' method.
-
-Besides the interface change, two minor aspects are worth noting. First, to
-improve safety, list model elements can no longer be copied. Second, to foster
-consistency with other parts of Genode's API, the 'apply_first' method has
-been renamed to 'with_first'.
-
-
-Pruned IRQ-session arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-So far, we have used the 'device_config_phys' argument of the IRQ session to
-implicitly request the use of _Message-Signalled Interrupts_ (MSI) to core.
-This argument specifies the address to the PCI configuration space. However,
-with the addition of Intel IOMMU support to the platform driver, we encountered
-an instance where we need an MSI for a non-PCI device in order to receive fault
-IRQs from the IOMMU. We therefore added an 'irq_type' argument to the IRQ
-session, which allows the explicit specification of whether a LEGACY interrupt
-or an MSI is requested.
-
-Yet, as we exceeded the character limit by adding another argument, we pruned
-the IRQ-session arguments: Since 'device_config_phys' is not relevant for
-LEGACY interrupts, we removed this from the default _Irq_connection_
-constructor. We further added an alternative constructor for MSI, which sets
-'device_config_phys' but omits the 'irq_trigger' and 'irq_polarity' arguments.
-
-
-Libraries and applications
-##########################
-
-Seoul virtual machine monitor
-=============================
-
-The Seoul/Vancouver VMM - introduced to Genode with release 11.11 - is an
-experimental x86-based VMM which runs on Genode@NOVA, Genode@seL4, and
-Genode@Fiasco.OC, and Genode@hw on Intel and on AMD hardware. It has been up
-to now solely used with 32-bit and special crafted VMs. With the addition of
-[https://genode.org/documentation/release-notes/22.11#Seoul_VMM - VirtIO support]
-for GPU, input, and audio, the usage as specialized tailored
-[https://genodians.org/alex-ab/2023-05-09-seoul-23-04 - disposable VMs] became
-quite comfortable.
-
-However, time is ticking for 32bit on x86 and some features aren't provided in
-the same quality as for 64bit VMs. For example, when using Firefox on 32bit,
-the video playback on some webpages gets denied while functioning on 64bit
-without complaints. So, the time came to extend the Seoul VMM by 64bit guest
-support to make it fit for today and avoid further hassles.
-
-Over the year 2023, the Seoul VMM got extended by enabling the instruction
-emulator - called Halifax - to decode
-[https://wiki.osdev.org/X86-64_Instruction_Encoding - x86_64 instructions]
-with additional prefixes and additional 8 general purpose registers. Besides
-the necessary deep dive through this special topic, the Seoul VMM required
-extensions to handle more than 4G guest physical memory. Several changes to
-the guest-memory layout handling and the memory-layout reporting, e.g.,
-[https://wiki.osdev.org/Detecting_Memory_(x86) - VBios e820], were necessary.
-
-Once an early prototype successfully booted a 64bit Linux kernel, we found the
-initial user task of some Linux distributions to fail by complaining about
-unsupported CPUs. As it turned out, glibc-based software (and later also
-llvm-based) have several detection mechanism to identify the running CPU - and
-if they feel uncomfortable, deny to work. So, we had to extend the support to
-report more of the native CPUID values of the host and as an after-effect,
-have to emulate more MSR accesses as performed by 64bit Linux guests.
-Unfortunately, the MSRs between Intel and AMD differ in subtle ways, so a per
-CPU differentiation became necessary in the vCPU model.
-
-Additionally, during testing of the native 64bit Debian VM installation with
-the Seoul VMM, several improvements during early boot, especially for the
-interactive usage of the GRUB bootloader were made. Ready to use packages to
-test drive the 64bit Seoul VMM on Sculpt OS are available via the "alex-ab"
-depot.
-
-[image seoul_64bit]
-  Two instances of the Seoul VMM executing 64-bit Linux
-
-
-Ported 3rd-party software
-=========================
-
-Linphone SIP client
--------------------
-
-Sculpt on the PinePhone used to provide only support for making and receiving
-regular phone calls but did not yet provide any VoIP functionality. Now, the
-"Linphone Console Client" and the "SIP Client for Ubuntu Touch" got ported to
-Genode to expand the available features on the PinePhone when it comes to
-mobile communication.
-
-We decided to port the [https://linphone.org - Linphone-SDK], the console
-client in particular, to Genode because it seems to be a time-tested solution
-on a range of OSes. Furthermore, it uses the [https://cmake.org - cmake]
-build-system, which makes it the ideal candidate for stressing
-[https://github.com/genodelabs/goa - Goa] with a reasonably complex project.
-Using Goa itself turned out to be straight-forward and by re-using the already
-existing back ends for POSIX-like systems, e.g. OSS for handling audio via the
-mediastreamer library, we only had to tweak the build-system in very few
-places. In the process, we encountered a few short-comings regarding the
-handling of shared libraries in cmake-based Goa projects. We were happy to
-address these and the fixes are part of the current Goa release.
-
-Since the user interface of the console client cannot be used comfortably on
-the PinePhone, it had to be complemented by a GUI application that handles the
-user interaction. While looking for such an application we noticed the
-[https://gitlab.com/ubports-linphone/linphone-simple/ - SIP Client for Ubuntu Touch]
-that utilizes the Ubuntu Touch UI Toolkit - where a port to Genode already
-exists. We adapted that project for our needs and - with the major components
-now in place - created a preset for Sculpt on the PinePhone.
-
-The preset's structure is depicted by the following chart.
-
-[image linphone_preset]
-  Structure of the linphone preset
-
-Each of the two components has its own requirements: The Linphone client needs
-access to the network, has to store its configuration, and requires access to
-the audio subsystem. It is the driving force behind the operation while it
-receives its instructions from the GUI. The GUI needs access to the GPU
-driver, as required for fluent rendering of QML on the PinePhone, as well as
-access to input events for user interaction.
-
-Naturally these requirements are satisfied by other components also
-incorporated into the preset:
-
-* The _Dynamic chroot_ component selects and limits the file-system access of
-  the client to the configured directory. In case of the PinePhone it points
-  to the '/recall/linphone' directory on the SD-card.
-
-* The _SNTP_ component provides the client with a correct real-time clock
-  value. Note that the SNTP component uses a different TCP/IP-stack than the
-  client itself.
-
-* The _Audio driver_ component makes the speaker as well as the microphone
-  available to the client.
-
-* The _GPU driver_ component allows the GUI to render the interface via OpenGL
-  on the GPU.
-
-* The _Touch keyboard_ collects the touch events and translates them into key
-  events that are then consumed by the GUI.
-
-The Linphone client and the GUI themselves are connected via the _terminal
-crosslink_ component where the control channel is formed by connecting stdout
-from the GUI to stdin from the client and vice versa.
-
-As denoted by the chart, the client actually functions as a _daemon_ that is
-running in the background, whereas the GUI is the _app_ the user interacts
-with.
-
-For more information and a usage guide, please refer to the corresponding
-[https://genodians.org/jws/2023-11-16-sip-client-for-genode - Genodians article].
-
-
-Socat
------
-
-We ported socat, a multipurpose relay (SOcket CAT), to Genode and created a
-ready-to-use pkg archive that allows for making a terminal session available
-on port '5555'.
-
-
-SDL libraries
--------------
-
-This release also makes more SDL-related libraries available on Genode.
-The common helper libraries like SDL2-image, SDL2-mixer, SDL2-net, and SDL2-ttf
-complement the SDL2 support, while the SDL-gfx library enhances the support
-of SDL1.2. All these libraries are located in the _genode-world_ repository.
-
-
-Device drivers
-##############
-
-USB device drivers updated to Linux 6.1.20
-==========================================
-
-With our ongoing effort to replace our traditional device-driver porting
-approach by our new
-[https://genode.org/documentation/release-notes/21.08#Linux-device-driver_environment_re-imagined - device-driver environment],
-USB-device drivers were subject to this porting effort during this release
-cycle. This includes the HID driver for keyboard, mouse, and touch support,
-the network driver, which supports USB NICs like AX88179 or the PinePhone's
-CDC Ether profile of its LTE Modem, as well as the USB modem driver that
-offers basic LTE-modem access for modems relying on the
-[https://www.usb.org/document-library/mobile-broadband-interface-model-v10-errata-1-and-adopters-agreement - MBIM]
-configuration.
-
-
-Architecture
-------------
-
-In contrast to the USB host-controller drivers, USB device drivers do not
-communicate with the hardware directly, but only send messages to the USB host
-controller through Genode's USB-session interface. So, from Genode's point of
-view, they can be classified as protocol stacks. Therefore, we based these
-drivers not on the DDE Linux version that offers direct hardware access, but
-on 'virt_linux' as described in release
-[https://genode.org/documentation/release-notes/23.05#WireGuard_improvements - 23.05].
-
-We replaced the actual Linux calls that create USB messages (like control,
-bulk, or IRQ transfers) by custom implementations that forward these messages
-through a USB client session to the host controller. The client-session
-implementation is written in C++. Since our DDE Linux strictly separates C++
-from C-code, we introduced a USB-client C-API that can be called directly by
-the replacement functions.
-
-The same goes for the services the USB drivers offer/use. These services
-are accessed through the respective C-APIs. For example, the HID driver
-communicates with Genode's event session through the event C-API and the NIC
-driver through the uplink C-API.
-
-
-USB HID driver
---------------
-
-The HID driver is a drop-in replacement of its predecessor. It still offers
-support to handle multiple devices at once, and the configuration remains
-unchanged.
-
-Note that we have dropped support for multi-touch devices, like Wacom, because
-touch was merely in a proof of concept state that should be redesigned and
-rethought for Genode if needed.
-
-
-USB modem
----------
-
-The LTE-modem driver (usb_modem_drv) has been integrated into the network
-driver (see below).
-
-
-USB net
--------
-
-The 'usb_net_drv' is a drop-in replacement for its predecessor with the
-exception that an additional configuration attribute is available:
-
-!<config mac="2e:60:90:0c:4e:01 configuration="2" />
-
-Next to the MAC address (like in the previous version), the USB configuration
-profile can be specified with the 'configuration' attribute. For USB devices
-that provide multiple configuration profiles, the Linux code will always
-select the first non-vendor-specific configuration profile found. This may not
-be the desired behavior, and therefore, can now be specified.
-
-The available configuration profile of a device can be found out under Linux
-using:
-
-! lsusb -s<bus>:<device> -vvv
-
-Currently the driver supports NICs containing an AX88179A chip and that offer
-the NCM or the ECM profile.  Support for the SMSC95XX line of devices has been
-dropped, but may be re-enabled if required.
-
-As mentioned above, the LTE modem support for MBIM-based modems has been
-merged into this driver because an LTE modem is merely a USB networking device
-(for data) plus a control channel. In case the driver discovers an LTE modem,
-it will announce a Genode terminal session as a control channel.
-
-Example configuration for the Huawai ME906s modem:
-
-!<start name="usb_net_drv">
-!  <resource name="RAM" quantum="10M"/>
-!  <provides>
-!    <service name="Terminal"/>
-!  </provides>
-!  <config mac="02:00:00:00:01:01" configuration="3"/>
-!  <route>
-!    <service name="Uplink"><child name="nic_router"/></service/>
-!    ....
-!  </route>
-!</start>
-
-The MBIM interface is enabled using configuration profile "3" and the service
-"Terminal" is provided.
-
-We have tested the driver mainly on Lenovo Thinkpad notebooks using Huawai's
-ME906e and Fibocoms's L830-EB-00 modems, but different modems might work as
-well.
-
-
-Current limitations
--------------------
-
-The current version of 'virt_linux' does not support arm_v6 platforms like
-Raspberry Pi (Zero). We will address this shortcoming with the next release
-and update the drivers accordingly.
-
-
-Platforms
-#########
-
-Linux
-=====
-
-Following the official
-[https://wiki.libsdl.org/SDL2/MigrationGuide - migration guide] of SDL, the
-fb_sdl framebuffer driver was updated from SDL1 to SDL2 by Robin Eklind.
-Thanks to this valuable contribution, fb_sdl is now ready to run on modern
-Linux installations especially in environments that use the Wayland display
-server. Note, to compile the component from source, the installation of
-libsdl2 development packages (e.g., libsdl2-dev, libdrm-dev, and libgbm-dev on
-Ubuntu/Debian) is required.
-
-
-Build system and tools
-######################
-
-Debug information for depot binaries
-====================================
-
-So far, the Genode build system created symbolic links to unstripped binaries
-in the _debug/_ directory to provide useful debug information, but binaries
-from depot archives did not have this information available.
-
-With this release, the 'create', 'publish' and 'download' depot tools received
-an optional 'DBG=1' argument to create, publish, and download 'dbg' depot
-archives with debug-info files in addition to the corresponding 'bin' depot
-archives.
-
-To avoid the storage overhead from duplicated code with archived unstripped
-binaries, we now create separate debug info files using the "GNU debug link"
-method in the Genode build system and for the 'dbg' depot archives.
-
-
-Decommissioned implicit trigger of shared-library builds
-========================================================
-
-Since the very first version, Genode's build system automatically managed
-inter-library dependencies, which allowed us to cleanly separate different
-concerns (like CPU-architecture-specific optimizations) as small static
-libraries, which were automatically visited by the build system whenever
-building a dependent target.
-
-When we later
-[https://genode.org/documentation/release-notes/9.11#Completed_support_for_dynamic_linking - introduced]
-the support for shared libraries, we maintained the existing notion of
-libraries but merely considered shared objects as a special case. Hence,
-whenever a target depends on a shared library, the build system would
-automatically build the shared library before linking it to the target.
-
-With the later introduction of Genode's ABI's in version
-[https://genode.org/documentation/release-notes/17.02#Genode_Application_Binary_Interface - 17.02],
-we effectively dissolved the link-time dependency of targets from shared
-objects, which ultimately paved the ground for Genode's package management.
-However, our build-system retained the original policy of building shared
-libraries before linking dependent targets. Even though this is arguably
-convenient when using many small inter-dependent libraries, with complex
-shared libraries as dependencies, one always needs to locally build those
-complex libraries even though the library internals are rarely touched or the
-library is readily available as a pre-built binary archive. In the presence of
-large 3rd-party libraries, the build system's traditional policy starts to
-stand in the way of quick development-test cycles.
-
-With the current release, we dissolve the implicit built-time dependency of
-targets from shared libraries. Shared libraries must now be explicitly listed
-in the 'build' command of run scripts. For example, for run scripts that build
-Genode's base system along with the C runtime, the build command usually
-contains the following targets.
-
-! core lib/ld init timer lib/libc lib/libm lib/vfs lib/posix
-
-However, in practice most run scripts incorporate those basic ingredients as
-depot archives. So those targets need to be built only if they are touched by
-the development work. To incorporate the results of all explicitly built
-targets into a system image, the 'build_boot_image' command can be used as
-follows. Note that the listing of boot modules does not need to be maintained
-manually anymore.
-
-! build_boot_image [build_artifacts]
-
-During the release cycle of version 23.11, we have revisited all run scripts
-in this respect, and we encourage Genode users to follow suit. The run tool
-tries to give aid to implement this change whenever it detects the presence of
-a .lib.so 'build_boot_image' argument that is not covered by the prior build
-command. For example, on the attempt to integrate 'ld.lib.so' without having
-built 'lib/ld', the following diagnostic message will try to guide you.
-
-! Error: missing build argument for: ld.lib.so
-!
-!   The build_boot_image argument may be superfluous or
-!   the build step lacks the argument: lib/ld
-!
-!   Consider using [build_artifacts] as build_boot_image argument to
-!   maintain consistency between the build and build_boot_image steps.
-
-The inconvenience of the need to adopt existing run scripts notwithstanding,
-developers will certainly notice a welcome boost of their work flow,
-especially when working with complex 3rd-party libraries.

doc/release_notes/24-02.txt

@@ -1,677 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 24.02
-              ===============================================
-
-                               Genode Labs
-
-
-
-Version 24.02 focuses on developer experience and framework infrastructure.
-Genode's Goa SDK has reached prominence in the past few releases. It largely
-streamlines the porting, development, and publishing of software targeting
-Genode and Sculpt OS in particular.
-With the current release, Goa has become able to conveniently use Sculpt OS as
-a remote test target. Regardless of whether targeting a PC or the PinePhone,
-either can be turned into a test target in seconds and the developer's
-compile-test cycle looks exactly the same
-(Section [Sculpt OS as remote test target for the Goa SDK]).
-
-A long anticipated infrastructure topic is the rework of Genode's audio stack
-to accommodate latency-sensitive scenarios, using flexible sample rates, and
-making audio drivers pluggable.
-Section [Revised audio infrastructure] gives an overview of the taken
-architectural approach, the interfaces, and a low-complexity mixer modelled
-as self-sufficient resource multiplexer.
-
-Speaking of infrastructure, we are excited to report to have wrapped up the
-transition to our modern Linux device-driver environment based on Linux 6.x.
-The last piece of the puzzle was the TCP/IP stack that was still based
-on code originating from Linux 4.4.3.
-Section [TCP/IP stack based on DDE-Linux version 6.1.20] details the new
-TCP/IP stack.
-
-According to our [https://genode.org/about/road-map - road map], we plan to
-add suspend/resume as feature to Sculpt OS 24.04. As a crucial stepping stone
-towards this goal, all drivers that cannot be easily restarted must become
-suspend/resume aware.
-Section [Suspend/resume awareness of GPU, AHCI, and NVMe drivers] explains
-this achievement for the AHCI, NVMe, and Intel GPU drivers.
-
-Further highlights of the release are the much improved handling of HID
-events including the generalized calibration of motion events, API safety
-improvements, the prospect of de-privileged tracing in Sculpt OS, and
-multi-client support for Vivante GPUs.
-
-On our road map, we had scheduled two further topics that are notably absent,
-namely USB and SMS. But don't fret. Even though the large rework of our USB
-infrastructure for fine-grained and dynamic USB access has been completed just
-in time, we felt that this far-reaching change should better not be rushed
-into the release. It will be merged shortly after, and settle into the upcoming
-Sculpt OS version 24.04 just fine. The second topic not covered is SMS support
-for the PinePhone, which is a topic actively
-[https://github.com/genodelabs/genode/issues/5127 - worked on] but with no
-user-visible effect until its integration in Sculpt OS in April.
-
-
-Revised audio infrastructure
-############################
-
-After first introduced in version
-[https://genode.org/documentation/release-notes/10.05#Device-class_interfaces_for_NIC_and_Audio-out - 10.05],
-Genode's
-[https://genode.org/documentation/genode-foundations/23.05/components/Common_session_interfaces.html#Audio_output - audio support]
-slowly evolved over the years, covering audio mixing in
-version
-[https://genode.org/documentation/release-notes/10.11#Audio_mixer - 10.11],
-leveraging OpenBSD's audio driver since version
-[https://genode.org/documentation/release-notes/15.05#Audio_drivers_ported_from_OpenBSD - 15.05]
-and offering the OSS interface as VFS plugin since version
-[https://genode.org/documentation/release-notes/20.11#Streamlined_ioctl_handling_in_the_C_runtime___VFS - 20.11].
-With our recent focus on use cases like
-[https://genodians.org/jws/2023-11-16-sip-client-for-genode - VoIP on the PinePhone] or
-[https://genode.org/documentation/release-notes/21.05#Webcam_support - video conferencing],
-however, we identified limitations that cannot be overcome without an
-architectural revision.
-
-First, in the name of simplicity, we used to tie the inter-component audio
-interfaces to a fixed sample rate of 44100 Hz. This has recently become a
-problem because some audio drivers tend to support only 48000 Hz.
-
-Second, in latency-sensitive scenarios, we observed that the existing
-interfaces were prone to effects caused by the drifting of time between the
-producer and consumer of audio data. One effect are buffer under-runs, which
-produce audible noise. The other is the slow accumulation of buffered sample
-data, which increases latency over time (affecting the effectiveness of
-acoustic echo cancellation) and yields an audible buffer overrun after a
-while.
-
-Third, the mixer is a single client of the audio driver, which makes the mixer
-dependent on the liveliness of the driver. Therefore, the driver cannot be
-restarted without also restarting the mixer and - transitively - each client
-of the mixer. The rigid relation between the audio driver and the mixer also
-stands in the way of routing audio between different audio devices operated
-by separate drivers.
-
-After having successfully introduced the concept of _pluggable drivers_ for graphics in version
-[https://genode.org/documentation/release-notes/20.08#The_GUI_stack__restacked - 20.08]
-and applying the same idea to networking in version
-[https://genode.org/documentation/release-notes/21.02#Pluggable_network_device_drivers - 21.02],
-the time was ripe for turning the audio infrastructure upside down.
-
-[image audio_vs_recordplay]
-  original layered architecture (left) compared to the new pluggable
-  architecture (right)
-
-The new architecture as shown on the right turns the mixer into a
-self-sufficient resource multiplexer, which offers a service for playing audio
-and a service for recording audio. Both audio drivers as well as audio
-applications are becoming mere clients of the mixer. With this architecture,
-the dynamic starting, removal, and restarting of the driver, of even multiple
-drivers, is trivially solved.
-
-To bridge the gap between audio clients operating at different sample rates,
-the mixer automatically detects and converts sample rates as needed. Both play
-and record clients are expected to operate periodically. The number of samples
-produced per period is up to each client and does not need to be constant over
-time. The mixer infers the used sample rates and periods by observing the
-behavior of the clients. It measures the jitter of clients to automatically
-adjust buffering parameters to attain continuous playback while trying to
-optimize for low latency. Those runtime-measurements can be augmented by
-explicit configuration values.
-
-Multi-channel playing and recording are realized by one session per channel
-whereas one channel is used to drive the time allocation while all further
-channels merely enqueue/obtain data into/from their respective sessions
-without any synchronous interplay with the mixer.
-
-The mixer routes and mixes audio signals produced by play clients to record
-clients according to its configuration. Typical play clients are an audio
-player or a microphone driver whereas typical record clients are an audio
-recorder or an audio-output driver. A simple mixer configuration looks as
-follows:
-
-! <config>
-!
-!   <mix name="left">  <play label_suffix="left"/>  </mix>
-!   <mix name="right"> <play label_suffix="right"/> </mix>
-!
-!   <policy label_suffix="left"  record="left"/>
-!   <policy label_suffix="right" record="right"/>
-!
-! </config>
-
-This configuration defines two signals "left" and "right" that are mixed from
-the audio input of the matching <play> clients. In the example, each play
-session labeled as "left" is mixed into the "left" signal. Each <mix> node can
-host an arbitrary number of <play> nodes. The same <play> policy can appear at
-multiple <mix> nodes. A <policy> node assigns a signal to a record client. In
-the example, a record client labeled "left" is connected to the <mix> signal
-"left".
-
-The mixer allows for the cascading of <mix> nodes. For example, the following
-signal "lefty" is a mix of the two signals "left" and "right", weighted by
-respective volume attributes.
-
-! <mix name="lefty">
-!   <signal name="left"  volume="0.7"/>
-!   <signal name="right" volume="0.3"/>
-! </mix>
-
-[image mixed_waveforms]
-  Example of the mixer output for a sine wave as the "left" signal (top),
-  a signal mixed 70:30, a signal mixed 30:70, and a square wave as the
-  "right" signal (bottom).
-
-The operation and configuration of the mixer is described in more detail by
-the accompanied README at _os/src/record_play_mixer/_. The inter-component
-interfaces are located at _os/include/play_session/_ and
-_os/include/record_session/_.
-
-The _gems/run/waveform_player.run_ script illustrates the integration of the
-mixer by using a waveform generator as multi-channel play client and an
-oscilloscope as record client.
-
-Current state and next steps
-----------------------------
-
-The new infrastructure is ready to be exercised by the synthetic example
-mentioned above as well as by the _audio_out.run_ and _audio_in.run_ scripts
-located at _repos/dde_bsd/run/_. The OpenBSD-based audio driver can be
-operated in either of two modes. By default, it is compatible to the old audio
-in/out interfaces. The new record/play mode can be enabled by setting the
-'record_play="yes"' config attribute. Over the next release cycle, we will
-successively convert the other pieces of the audio stack, in particular the
-other drivers and the OSS VFS plugin, to the new record and play interfaces.
-Following this transition, the original audio in/out interfaces will be
-removed.
-
-
-Sculpt OS as remote test target for the Goa SDK
-###############################################
-
-The run-stage generalization from
-[https://genode.org/documentation/release-notes/23.08#Run-stage_generalization - release 23.08],
-paved the way for the new run-target "sculpt" that allows using Sculpt OS as
-a remote test target for 'goa run'. Since Goa already placed all the required
-files for running a scenario into a _var/run_ directory, adding this target
-merely involved coming up with a solution for synchronizing the run directory
-with Sculpt OS and getting a hold of the log output. The implementation in Goa
-is accompanied by a _goa_testbed_ package that starts a remotely-controlled
-subsystem on Sculpt OS. It particularly hosts a _lighttpd_ and _tcp_terminal_
-component. The former is used for run-directory synchronization based on HTTP
-PUT. The latter provides the log output of the test scenario via telnet. For
-more details, you may take a look at the corresponding
-[https://genodians.org/jschlatow/2024-01-29-goa-sculpt - blog post on genodians.org].
-
-In order to integrate support for this mechanism into Sculpt OS, we
-supplemented the NIC router configuration with a _http_ and a _telnet_ domain.
-Each of these domains is intended to accommodate a single client. Ports 80 and
-23 of the _uplink_ domain are then forwarded to the clients in the _http_ and
-_telnet_ domain respectively. This is complemented by the _goa_testbed_ preset
-added to the PC and PinePhone version of Sculpt OS that turns the system into
-a ready-to-use remote test target. You can see this feature in action in our
-[https://genodians.org/nfeske/2024-02-15-fosdem-aftermath - FOSDEM talks].
-
-When implementing the Sculpt target in Goa, we also had to come up with a way
-to supply Goa with the IP address of the remote test target. Goa's modularity
-w.r.t. custom run stages motivated us to implement a generic mechanism for
-target-specific options. For this purpose, we added the config variable
-'target_opt' that is defined as a Tcl array. The Sculpt target evaluates the
-array elements 'sculpt-server', 'sculpt-port-http' and 'sculpt-port-telnet'.
-We further augmented Goa's command-line parsing such that individual elements
-of the 'target_opt' as well as the 'version' config variables, which are both
-arrays, can be supplied as command-line arguments. The corresponding arguments
-follow the pattern '--target-opt-<option>' and '--version-<user>/<type>/<name>'.
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-TCP/IP stack based on DDE-Linux version 6.1.20
-==============================================
-
-Over the course of the previous four releases, we have gradually modernized
-the arsenal of Linux-based drivers to use our modern Linux device-driver
-environment based on Linux 6.x.
-The final piece of code standing in the way of the removal of our legacy DDE
-Linux approach has been Linux's TCP/IP stack. The stack was based on Linux
-version 4.4.3 and did not even take advantage of lx_kit supported features
-like cooperative scheduling.
-
-For this reason, it was about time to update the TCP/IP port while also
-adapting it to our
-[https://genode.org/documentation/release-notes/21.08#Linux-device-driver_environment_re-imagined - modern]
-DDE approach. Being in such an ancient state, this effort ended up being more
-of a re-write than an actual update. The IP stack is also one of the few DDE
-Linux components that is a shared library, as opposed to most drivers, which
-are executable binaries. This led to improvements of our lx_kit, for example,
-we had to replace static C++ constructors by automatically generated functions
-for kernel module-initialization calls because C++ constructors are supposed
-to be called by the binary and not during library initialization
-(Section [Linux-device-driver environment (DDE)]).
-Additionally, we took the opportunity of experimenting with a socket C-API
-with the ultimate goal to replace the VFS plugins for Linux (vfs_lxip) and
-lwIP (vfs_lwip) with a unified version, but this is an ongoing effort.
-Nevertheless, with the current release, the update of our Linux TCP/IP port is
-complete and, from a user perspective, the new version as well as the updated
-VFS plugin are drop-in replacements for version 4.4.3. The transition should
-be seamless.
-
-While porting the IP stack, we also investigated a long-standing issue
-regarding the memory consumption of the IP stack, which always seemed a little
-too high. We were able to identify the hash tables used for locating sockets
-as the main reason. These tables are configured for server loads per default
-(meaning > 1 million sockets), which Genode with one or few (VFS server)
-clients per IP stack does not default to. This enabled us to reduce the amount
-of hash table allocations during IP stack initialization, which leads to
-reduced memory demands (>10MB) of the IP stack.
-
-With the new IP stack in place and no legacy components remaining, we removed
-the DDE Linux port file (_dde_linux.port_) and the legacy lx_kit/lx_emul
-marking the update to the current DDE approach as complete.
-
-
-De-privileged tracing
-=====================
-
-Genode got equipped with a light-weight event tracing facility in
-[https://genode.org/documentation/release-notes/13.08#Light-weight_event_tracing - version 13.08].
-The underlying core service - appropriately named TRACE - used to be an
-outlier among core's services in that it provided a privileged interface with
-system-global reach. A trace client is assumed to play a privileged role and
-must be ultimately trusted. This is arguably fine for the typical use cases
-where event tracing is used in the lab. However, anticipating on-target
-debugging on Sculpt OS, the desire for on-target tracing by untrusted trace
-monitors casually running on Sculpt OS is anything but far-fetched. To allow
-for the secure use of untrusted trace monitors, the global reach of core's
-trace service is no longer satisfactory.
-
-The current release changes core's trace service to expose trace subjects
-only if their PD label matches up with the label of the trace monitor. Hence,
-by default, a trace monitor can only observe itself and its child components.
-Only if the trace monitor's parent rewrites the trace-session's label, the
-view of the trace monitor can become broader. For example, when rewriting the
-trace label to an empty string "", the trace monitor becomes able to observe
-the sibling components hosted in the same init instance as the trace monitor.
-Note that the trace-subject label as reported as subject info to a trace
-monitor is now given relative to the label of the trace session.
-
-To grant a trace session the special privilege of obtaining a global
-system view (including the kernel's trace subjects), the top-level init
-has to rewrite the session's label to an empty string. At core, this
-specific label "init -> " is handled as a special case that discharges
-the namespacing of trace subjects.
-
-In Sculpt OS, the user can now select one of three options when connecting a
-trace monitor to core's trace service. The "component" option restricts the
-tracing to the trace monitor itself, the "deployment" option exposes the
-entire runtime subsystem to the trace monitor, whereas the "system" option
-exposes the entire Sculpt system to the trace monitor. The latter two options
-require adequate trust in the trace monitor.
-
-
-Deferred unlinking of files in VFS RAM file systems
-===================================================
-
-UNIX systems defer the physical deletion of a file until the last file
-descriptor referring to the file is closed. Since Genode's VFS does not (try
-to) implement this scheme, we encountered a few difficulties while porting
-3rd-party software to Genode. In some situations, a parent process of a
-Unix-like subsystem may pass the content of an unlinked file to a forked child
-process. This can be observed when using the 'exec' command in Tcl scripts.
-Another example is the use of the 'tmpfile()' POSIX function.
-
-In the use cases we observed, the mechanism was merely used for _/tmp_ files,
-which are usually backed by a '<ram>' file system in Genode's VFS. Hence, to
-accommodate these programs, we changed the unlink operation of the ram fs to
-defer the destruction of a file until it is no longer referenced by any VFS
-handle. When unlinked, the file no longer appears in the directory.
-But it can still be opened and accessed.
-
-
-Improved API safety of MMIO accesses
-====================================
-
-The 'Register' respectively 'Mmio' APIs have become predominant in Genode's
-native drivers where the type-safe access to hardware registers has become a
-second nature. However, up until recently, one point of uncertainty remained:
-Since the 'Mmio' utility evaluated only the base address of a memory-mapped
-I/O range, all associated register definitions were assumed to be fully
-contained within the corresponding local memory mapping. An accidental
-violation of this assumption would remain undetected.
-
-The current release replaces this optimistic assumption by a combination of
-two mandatory upper-bounds checks. Each 'Mmio' instance is now qualified with
-a 'size_t' template parameter denoting the size of the memory-mapped I/O range
-in bytes. Each register definition within the 'Mmio' is statically checked
-against this upper bound at compile time. At runtime, the local memory mapping
-of the I/O range is checked against the statically defined 'Mmio::SIZE'.
-A violation is considered a non-recoverable driver bug, prompting an error
-message along with a 'Range_violation' exception.
-
-This change modifies the API. Existing driver code must be adapted in two
-respects. First, each 'Mmio' definition must be annotated with the expected
-size in bytes as template argument. Second, the 'Mmio' constructor requires a
-'Byte_range_ptr' argument instead of a plain 'addr_t' value.
-
-
-Application-level VFS file watching
-===================================
-
-The convenience API at _os/vfs.h_ provides utilities for using the VFS as
-a stand-alone library without depending on the libc. Among its utilities,
-there exists the so-called watch handler that can be used to monitor file
-modifications. As watch handlers were primarily used by VFS plugins and
-the C runtime, they used to operate in the context of low-level I/O signal
-handlers. Code executed in this context should generally not involve any
-global side effects that depend on I/O signals themselves (like synchronous
-file access).
-
-With the current release, the 'Watch_handler' becomes safe to use at
-application level where global side effects are anticipated. The former use
-case is now covered by the dedicated 'Io::Watch_handler'.
-
-
-Device drivers
-##############
-
-Linux-device-driver environment (DDE)
-=====================================
-
-ARMv6 compatibility
--------------------
-
-In the previous release, we updated our
-[https://genode.org/documentation/release-notes/23.11#USB_device_drivers_updated_to_Linux_6.1.20 - USB device drivers]
-to Linux 6.1.20 using 'virt_linux'. Drivers or protocol stacks based on
-'virt_linux' do not access hardware directly. They either communicate through
-another instance - like the USB host controller for USB device drivers - with
-the hardware or do not require hardware at all (e.g., TCP/IP, WireGuard).
-
-The 'virt_linux' flavour is still CPU-architecture specific because it
-contains low-level assembly code. A limitation of Genode release 23.11 was
-that there is no support for ARMv6 in 'virt_linux'. As devices based on ARMv6
-can still be found in the wild (e.g., Raspberry Pi Zero), the current release
-supplements support for ARMv6 to 'virt_linux', the USB device drivers, and the
-TCP/IP stack. For this to work, we had to separate code shared by ARMv6 and
-ARMv7 platforms. In many places, there would be a directory like _spec/arm_,
-which would contain build rules or code for both architectures. ARMv6 and
-ARMv7 have many things in common - until they don't. With the current release,
-we have split these folders into _arm_v6_ and _arm_v7_ respectively and while
-we were at it renamed _arm_64_ into _arm_v8_ for consistency. With this
-approach, it became possible to introduce ARMv6 and ARMv7 specific kernel
-configurations to 'virt_linux', and thus, enable support for drivers/protocol
-stacks for both architectures.
-
-
-Initcall handling without relying on global constructors
---------------------------------------------------------
-
-When porting Linux drivers, a lot of code is placed into modules. Modules
-always have a magic module-function call (e.g., 'module_init'), which
-registers a function for the initialization of the module and is executed
-during kernel startup prior device probing. DDE Linux mapped 'module_init'
-indirectly to a macro that generated a function as a static constructor
-(ctor), which in turn registered the required module function (Note: This is
-simplified because there is also an order that must be preserved). This
-solution required all ported components to call 'exec_static_constructors' in
-order to trigger the registration of module-init calls before executing any
-other Linux kernel code, but not before the 'Lx_kit' initialization because
-the init-call functions had to be registered in advance. This scheme led to
-hen-and-egg problems in our TCP/IP stack
-(Section [TCP/IP stack based on DDE-Linux version 6.1.20]) and our WiFi driver
-port because they are shared libraries where static constructors must be
-called at a later stage.
-
-In order to avoid these kinds of problems, we changed the module-init approach
-by replacing the macro-generated functions with global-function pointers with
-a well known prefix. These pointers are collected by the DDE-Linux-build
-system using ELF reading tools (i.e., 'nm') after the compile step and are
-placed into a function ('lx_emul_register_initcalls') which is called during
-'Lx_kit' startup. This way, no changes to existing drivers are necessary, and
-the static constructor problem disappeared for the shared library cases.
-
-Note: Any ported driver still using 'exec_static_constructors' can remove the
-call after checking if there are no static constructors from other C++ objects
-present.
-
-
-Suspend/resume awareness of GPU, AHCI, and NVMe drivers
-=======================================================
-
-As a further step towards general ACPI suspend/resume support, our
-custom-developed drivers for Intel GPU, NVME, and AHCI got re-worked to
-cooperate with the feature.
-
-Before the final suspend, the drivers can now be notified to stop processing
-further client data and to shut down the devices used by closing the
-'Platform::Device'. This prompts the platform driver to power-off the
-corresponding PCI device. However, DMA buffers containing all the client data
-are kept in memory and are not de-allocated. This means that the client
-sessions for GPU and 'Block_session' can stay intact (for ACPI S3 - suspend to
-memory) and don't require a restart of the users of GPU, NVME, and AHCI on
-resume.
-
-On resume, after the kernel is up again, the drivers need to get notified to
-re-acquire the PCI device from the platform driver. The platform driver will
-power-on the re-acquired devices and the GPU/NVME/AHCI drivers will set up the
-device resources, e.g. MMIO and IRQ, and then re-initialize the devices. The
-drivers will finally restart processing session requests. This way the clients
-will just continue to operate as though nothing had happened.
-
-The test scenario for suspend/resume can be test-driven by using
-_run/acpi_suspend_, which contains a periodic suspend-resume cycle for
-developing purposes.
-
-
-Dynamic aperture handling for high resolution framebuffers
-==========================================================
-
-We extended the Intel GPU driver with a configuration option to specify the
-amount of the graphics aperture provided to the ported Intel display driver.
-Beforehand it was a fixed amount (64M), which may not suffice for all
-use-cases. The aperture is a shared resource, which must be used for various
-GPU-related internal data structures and is used from CPU side for access to
-the framebuffers by the display driver. When the display driver sets up
-several framebuffers with high resolutions, the fixed amount may be too small.
-The snippet below shows the new configuration option and the default value:
-
-! <start name="intel_gpu_drv" ...>
-!   <resource name="RAM" .../>
-!   <provides>
-!     <service name="Gpu"/>
-!     <service name="Platform"/>
-!   </provides>
-!   <config max_framebuffer_memory="64M">
-!   ...
-
-
-Improved human-interface device handling
-========================================
-
-In preparation of the _support for I2C-based HID (touchpad) devices_
-[https://genode.org/about/road-map#February_-_Release_24.02 - road-map item],
-we dusted off several aspects of our input-event handling from the drivers
-over the event API to the event-filter component. At the heart of the
-improvements, we developed a broad understanding of the specifics of the
-different motion-event device types that are widely in use. First, there are
-mice and touchpads, which generate relative-motion events that are translated
-by the GUI stack to movements of the GUI pointer. Then, we have three kinds of
-absolute-motion devices: pointers (e.g., Qemu usb-tablet or IP-KVM device like
-[https://pikvm.org/ - PiKVM]), touchscreens, and graphics-tablet tools (e.g.,
-stylus). These devices require translation of device-specific absolute
-coordinates to screen coordinates.
-
-On the driver side, we rewrote our custom *evdev* driver that interfaces
-with all current and future ported Linux input drivers. Now, evdev covers
-all peculiarities of the different device types, for example, touch devices
-that report up to 16 event slots (resp. fingers), and reports them via
-Genode Event sessions. Also, we implemented minimal "gesture" support for
-simple tap-to-click for touchpads that could be improved in the future,
-e.g., by two-finger-scrolling. Based on the rewrite, we could easily enable
-support for the Magic Trackpad in usb_hid_drv.
-
-The event filter was extended by a filter node to transform touch and
-absolute-motion event coordinates by a sequence of primitives expressed in
-sub-nodes, namely translation (move), scaling, rotation, and flipping.
-For example, the scaling of 32767x32767 touch coordinates to a FullHD screen
-is configured like follows. All primitives are documented in the event-filter
-README file.
-
-! <transform>
-!   <input name="usb"/>
-!   <scale x="0.0586" y="0.0330"/>
-! </transform>
-
-Additionally, the event filter now supports to optionally log motion and touch
-events beside keys and buttons.
-
-! <log motion="true"> <input name="usb"/> </log>
-
-Unfortunately, the developments outlined above delayed the actual integration
-of the prospected I2C HID support to a later release.
-
-
-Multi-client use of Vivante GPU (i.MX8)
-=======================================
-
-In this release, we brought our port of the etnaviv driver, which was still
-limited to one client only, up to speed. It now joins the other GPU drivers in
-providing multi-client support.
-
-Back in release
-[https://genode.org/documentation/release-notes/21.11#Vivante_GPUs__i.MX8_ - 21.11],
-we added support for the Vivante GC7000L GPU featured in the i.MX8MQ SoC to
-Genode via a port of the etnaviv Linux and Mesa3D driver. As a blueprint, it
-served us well when enabling another GPU for a different ARMv8 SoC, namely the
-Mali GPU in the PinePhone. The etnaviv port itself, however, never left its
-initial state and was able to cater to one client only. For this reason it was
-co-located and deployed in tandem with the client requiring its service. This
-factor somewhat restricted its usefulness in Sculpt when used in a
-desktop-like capacity on, e.g., the MNT Reform.
-
-The current release lifts this limitation and enables the driver to accommodate
-multiple clients at the same time.
-
-
-Libraries and applications
-##########################
-
-VirtualBox
-==========
-
-As a debugging aid, we enabled the reporting of Windows Blue Screen of Death
-(BSOD) reasons in our VirtualBox port. To enable the output, the new release
-adds a default of '+dbgf+gim' to the 'VBOX_LOG' environment variable. With
-VirtualBox Guest Additions installed in the Windows guest, after a "Guest
-indicates a fatal condition!", the reason for the blue screen will be printed
-to the log.
-
-
-Seoul VMM
-=========
-
-Several improvements got added since the previous Genode release, which showed
-up during daily use of a Genode developer VM. On the one hand, the exported
-guest-cursor shape was a bit offset from its actual position. Besides the
-guest shape, small hot_x, hot_y shifts are exported, which are now considered
-in order to position the mouse cursor shape more accurately. Additionally, the
-processing of alt-gr and <>| keys on German keyboard layouts got enabled.
-Finally, the AHCI model and the bindings to the Genode block session got
-reworked. Up to now, the AHCI model could not cope with delaying a block
-request in case the block session was saturated. Instead of making temporary
-copies, as done before, the AHCI model now supports keeping guest requests in
-guest memory when necessary and resumes block operations as soon as the block
-session is able to process more requests.
-
-
-Lighttpd web server version 1.4.73
-==================================
-
-We updated our port of the [https://www.lighttpd.net - lighttpd] HTTP server
-and at the same time also extended its feature-set by enabling the WebDAV
-module.
-
-Rather than being used as a general purpose HTTP server that comes with all
-bells and whistles, it powers our [https://genodians.org - Genodians]
-appliance in static fashion and with WebDAV in place is now also the
-foundation for the goa testbed introduced in
-Section [Sculpt OS as remote test target for the Goa SDK].
-
-
-Jitterentropy version 3.4.1
-===========================
-
-Back in 2014, we ported the
-[https://www.chronox.de/jent/index.html - jitterentropy library] as a basic
-component-local entropy source for seeding pseudo random-number generators like
-[https://prng.di.unimi.it/ - Xoroshiro] or [https://www.pcg-random.org/ - PCG].
-As the last port update dates back years, we brought the most recent version
-3.4.1 of jitterentropy to Genode. The new library is API-compatible to the old
-version and can be integrated as usual via the '<jitterentropy>' plugin into
-your VFS configuration.
-
-
-Build system and tools
-######################
-
-Goa SDK
-=======
-
-In addition to the support for using Sculpt as test target for Goa
-(Section [Sculpt OS as remote test target for the Goa SDK]), the latter
-underwent quite a few usability adjustments.
-
-As announced in
-[https://genode.org/documentation/release-notes/23.08#Support_of_index_projects - release 23.08],
-Goa has been enabled to export and publish a personal depot index. The depot
-index lists the depot user's packages in a nested structure of '<index>' nodes.
-The initial support for index projects, however, was restricted to two levels
-of '<index>' nodes. We eliminated this restriction in order to clear the path
-for large depot indexes with hierarchical structure.
-
-When using Goa to export and publish a depot index, one always had to provide
-the '--depot-overwrite' switch in order to overwrite the current depot index.
-Goa also propagated this switch to any sub-project that got exported along
-with the depot index. In practice, however, an index project will typically be
-exported and published when development on all sub-projects has finished,
-hence there is no need for re-exporting already exported sub-projects.
-We therefore added the '--depot-retain' switch in order to express the intent
-to not overwrite any depot content. Instead of propagating the
-'--depot-overwrite' switch, Goa now uses the '--depot-retain' switch when it
-automatically exports sub-projects.
-
-Along with the support for index projects, Goa had been equipped with the
-ability to lookup version information from other project directories. By
-default, Goa uses the current working directory as a starting point for the
-lookup of projects and their versions. The practical use of this was still
-limited, though, since it required using the '-C' argument to execute Goa
-from a different directory than the project directory. We thus introduced the
-'search_dir' config variable that allows defining the directory from which Goa
-starts searching for depended on projects.
-
-When porting CMake-based projects with Goa, we often needed to patch the
-_CMakeLists.txt_ or add quirks to Goa in order to disarm CMake's
-'find_library' command. Instead of resorting to those ad-hoc solutions, we
-decided to add support for _FindXXX.cmake_ files in api archives. Any api
-archive mentioned in the _used_apis_ file is now added to the
-'CMAKE_MODULE_PATH' so that CMake is able to correctly identify the presence
-of depended on libraries via the _FindXXX.cmake_ files. An example is found
-in the Goa repository at _examples/cmake_sdl2_.
-
-In addition to the aforementioned changes, we added a couple of minor tweaks:
-
-* We added the sub-commands 'goa help index' and 'goa help runtime' to document
-  the structure of _index_ and _runtime_ files.
-* The sub-command 'goa bump-version' now creates a _version_ file if none exists.
-
-
-Convenient parsing of backtraces
-================================
-
-The new _tool/backtrace_ parses the copied and pasted shared library info of a
-component (generated with <config ld_verbose="yes"/>) and the log output of the
-'Genode::backtrace()' function and prints the corresponding source locations in
-a convenient way.

doc/release_notes/24-05.txt

@@ -1,740 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 24.05
-              ===============================================
-
-                               Genode Labs
-
-
-
-The main driver behind Genode 24.05 was the
-[https://genode.org/news/sculpt-os-release-24.04 - recent release] of Sculpt
-OS 24.04 ([https://genodians.org/nfeske/2024-04-26-sculpt-os - What's new?]).
-Among the many usability advances of Sculpt OS is the flexible assignment
-of USB devices to components and virtual machines.
-Section [Fine-grained and dynamic assignment of USB devices/interfaces]
-introduces the underpinnings that made our new quality of life possible.
-Another user-facing feature with a surprisingly deep technical reach is
-suspend/resume. Section [Suspend/resume infrastructure] details the changes of
-the framework on that account. The new ability of seamlessly using the GNU
-debugger on top of Sculpt OS is a game changer for developers
-(Section [On-target debugging using the GNU debugger (GDB)]).
-Further user-visible and user-audible topics are the support for
-high-resolution displays and the wrapped-up transition to our new audio stack
-(Section [Transition to the new audio interfaces introduced in 24.02]).
-
-Besides the many usability-motivated topics of our
-[https://genode.org/about/road-map - road map], however, we celebrate
-the break-through of running Sculpt OS directly on our custom microkernel
-alternatively to using a 3rd-party kernel.
-Section [First version of Sculpt OS based on Genode's custom kernel]
-details the background story, the showstoppers we had to overcome, and the
-prospects of this achievement.
-
-: <div class="visualClear"><!-- --></div>
-: <p>
-:  <div style="clear: both; float: left; margin-right:20px;">
-:   <a class="internal-link" href="https://genode.org/documentation/genode-foundations-24-05.pdf">
-:    <img class="image-inline" src="https://genode.org/documentation/genode-foundations-title.png">
-:   </a>
-:  </div>
-: </p>
-
-The "Genode Foundations" book covers Genode's architecture, developer work
-flows, and reference material. In tandem with the current release, the
-document received its annual update, which includes not only adjustments
-to the most recent version but also new material about accessing GPIO pins,
-audio, debugging, and prominent APIs like the list model.
-
-Further topics of the current release reach from timing and network-throughput
-optimizations, over the profound rework of storage encryption, to updated
-3rd-party software such as Mesa, libSDL2, and Curl.
-
-: <div class="visualClear"><!-- --></div> <p></p>
-
-
-First version of Sculpt OS based on Genode's custom kernel
-##########################################################
-
-The ability to use a wide variety of kernels is certainly a distinctive
-feature of Genode. Since the very first version, the framework accommodated
-both a microkernel and the Linux kernel.
-Over the years, we embraced most members of the L4 family of kernels
-([https://genode.org/documentation/release-notes/9.05#Supporting_the_OKL4_kernel_as_new_base_platform - OKL4],
-[https://genode.org/documentation/release-notes/9.02#Genode_on_L4ka__Pistachio - Pistachio],
-[https://genode.org/news/genode-os-framework-release-8.08 - Fiasco],
-[https://genode.org/documentation/release-notes/10.02#Codezero_kernel_as_new_base_platform - Codezero]),
-all object-capability microkernels we could get our hands on
-([https://genode.org/documentation/release-notes/10.02#NOVA_hypervisor_as_new_base_platform - NOVA],
-[https://genode.org/documentation/release-notes/11.02#Support_for_Fiasco.OC - Fiasco.OC],
-[https://genode.org/documentation/release-notes/15.05#Proof-of-concept_support_for_the_seL4_kernel - seL4]),
-and even combined the framework with a static isolation kernel
-([https://genode.org/documentation/release-notes/15.08#Genode_on_top_of_the_Muen_Separation_Kernel - Muen]).
-
-Confronting the framework with largely different kernel mechanisms has
-undoubtedly strengthened Genode's software design, but also gave us a great
-depth of insights into the landscape of kernel designs and the implications of
-the respective design choices. It did not take us long to question some of
-these choices, and we started experimenting with custom kernel designs on our
-own. This work made its first appearance in version
-[https://genode.org/documentation/release-notes/11.02#Approaching_platform_support_for_Xilinx_MicroBlaze - 11.02]
-targeting Xilinx Microblaze softcore CPUs.
-Without haste, we steadily evolved this kernel as a research endeavour, mainly targeting ARM CPUs
-([https://genode.org/documentation/release-notes/14.05#Multi-processor_support - SMP],
-[https://genode.org/documentation/articles/trustzone - TrustZone],
-[https://genode.org/documentation/release-notes/15.02#Virtualization_on_ARM - virtualization],
-[https://genode.org/documentation/release-notes/19.08#64-bit_ARM_and_NXP_i.MX8 - 64 bit]),
-and later also addressing the
-[https://genode.org/documentation/release-notes/15.05#Feature_completion_of_our_custom_kernel__base-hw_ - x86]
-architecture.
-
-When we
-[https://genode.org/documentation/release-notes/18.02#Sculpt_for_Early_Adopters - started]
-creating Sculpt OS as a Genode-based operating system for commodity PCs, we
-picked NOVA as kernel of choice. NOVA's unique combination of microkernel and
-virtualization mechanisms served us extremely well. It is truly a technical
-marvel! But like any other 3rd-party kernel, it imposes certain complexities
-and points of friction onto the user land. In contrast to 3rd-party kernels
-like NOVA or seL4, which are self-sufficient programs, our custom kernel is
-melted with Genode's core component. This alleviates redundant data structures
-between kernel and user space and makes Genode's resource management directly
-applicable to kernel objects. In other words, it fits like a glove. Hence,
-looking ahead, we foresee a much simpler and ever more coherent trusted
-computing base of Sculpt OS.
-
-In order to realize this vision, we had to tackle a couple of long-time
-showstoppers. First of all, we needed to move IOMMU support out of the kernel
-into the user-level platform driver to render it kernel-agnostic. We completed
-a major part of this transition with
-[https://genode.org/documentation/release-notes/23.11#Kernel-agnostic_DMA_protection - release 23.11].
-
-Second, virtualization of commodity operating systems is a common use case for
-Sculpt installations, ours at Genode Labs included. Therefore, adding support
-for Intel's Virtual-Machine Extensions (VMX) was another important missing
-piece of the puzzle. Under the hood, we refactored and generalized the
-kernel's x86 hypervisor support to allow for the selection of the available
-virtualization technology at runtime and consolidated code for page-table
-handling. Even though we still have some way to go before the kernel is ready
-to replace the time-tested NOVA hypervisor as the default kernel for Sculpt
-OS, this release is a milestone in that direction.
-
-The Sculpt OS variant using our custom kernel is now available as a
-ready-to-use system image at [https://depot.genode.org/jschlatow/image]
-for Intel systems up to 8th generation core processors (Whiskey Lake).
-Note, when using Sculpt's integrated update mechanisms, you must already run
-at least Sculpt 24.04. The system image includes a launcher for running a
-Tiny-Core-Linux VM with a Firefox browser in VirtualBox. The launcher requires
-a window manager that is best deployed by switching to the corresponding
-preset. You also need to enable the _system clock_ and _mixer_ options.
-
-Note that there are still a few areas of improvement for this Sculpt variant:
-The IOMMU support currently omits IRQ remapping, which is important to shield
-the system from rogue devices sending arbitrary interrupts. Moreover, we plan
-to improve the kernel scheduling for interactive and time-critical workloads.
-
-
-Fine-grained and dynamic assignment of USB devices/interfaces
-#############################################################
-
-USB support has a long history within the Genode framework and for almost one
-decade its client session API has remained stable. Back in
-[https://genode.org/documentation/release-notes/15.02#USB_session_interface - 2015],
-we split the USB host-controller driver parts from other USB client device
-drivers. Since then, a USB client component could request exactly one USB
-device per session from the USB server resp. USB host-controller driver.
-Moreover, a client had to drive the device in its entirety.
-
-This former approach led to some limitations and intricateness. First, USB
-drivers capable of driving more than one device of the same class needed to
-know each device to request in advance. This information was not delivered by
-the USB session but by means of configuration. The out-of-band information
-path complicated the management of USB devices in complex systems like Sculpt
-OS, e.g., when passing arbitrary USB devices to a guest OS running inside a
-virtual machine.
-
-The second drawback was related to USB devices with multiple interfaces of
-different interface classes, most prominently, USB headsets with extra buttons
-for volume control. Such devices typically have several USB interfaces for
-audio playback and recording, and at least one interface for HID input events.
-Whereas the development of one driver for each interface class is certainly an
-attainable goal, creating driver mixtures for each potential combination of
-interfaces is unrealistic. Ultimately, we strive to freely operate different
-interfaces of a single device by dedicated drivers.
-
-These limitations accompanied us for quite some time, and a design to overcome
-them matured at the back of our minds. With the current release, the USB
-session eventually received its long-anticipated redesign.
-
-The new USB session API provides a _devices_ ROM to its client. Within this
-ROM a client can retrieve all relevant information about existing devices it
-is allowed to access. You can think of it as a virtual private USB bus for
-this client. When a new device gets connected that matches the client's policy
-of the USB host controller driver, the ROM gets updated appropriately. If a
-device gets removed physically, it'll vanish from the _devices_ ROM, which
-may, for example, look as follows.
-
-! <devices>
-!   <device name="usb-1-10" class="0x0" product="USB Optical Mouse"
-!           vendor_id="0x1bcf" product_id="0x5" speed="low" acquired="true">
-!     <config active="true" value="0x1">
-!       <interface active="true" number="0x0" alt_setting="0x0"
-!                  class="0x3" subclass="0x1" protocol="0x2">
-!         <endpoint address="0x81" attributes="0x3"
-!                   max_packet_size="0x7"/>
-!       </interface>
-!     </config>
-!   </device>
-! </devices>
-
-As can be seen in the example, the human-readable XML representation of the
-USB devices already contains most information that normally resides in the
-full-length device descriptor of the USB standard. That means a driver can
-parse relevant information about available configurations, interfaces, and
-endpoints - including their types and identifiers - without the need to
-communicate with the device in the first place.
-
-Besides the _devices_ ROM, the new USB-session API consists of an acquire
-function and a function to release a formerly acquired device. The acquisition
-of a device returns a capability to a new device RPC API. This distinct API
-includes a function to obtain a packet-stream buffer to exchange USB control
-requests with the USB host-controller driver. The host-controller driver
-sanity-checks the control requests, and potentially forwards them to the
-device. Thereby, a client can change the configuration of the device, enable
-an alternate interface, or request additional descriptors regarding
-device-class specific aspects.
-
-Moreover, the device RPC API provides functions to acquire or release an
-interface of the device. When acquiring an interface, a capability to the
-interface RPC API gets returned. This third new RPC API provides a
-packet-stream buffer to the client, which allows for the exchange of
-interrupt, bulk, or isochronous transfers with the host-controller driver.
-The host-controller driver checks these transfer requests for plausibility,
-and forwards them directly to the device and vice versa.
-
-The whole internals of the different RPC API layers, however, are not imposed
-on the developer. Instead, convenient helper utilities are provided within
-_repos/os/include/usb_session/device.h_. Those helper classes simplify the
-acquisition of USB devices and interfaces. Moreover, they support the notion
-of USB Request Blocks (Urbs) on the level of device (control) and interface
-(irq, bulk, isochronous). For an example component that makes use of these
-utilities, please refer to the USB block driver.
-
-All components that directly use the USB session have been adapted to the new
-API. This includes the Linux USB driver ports for host controllers, HID, USB
-Ethernet cards, the libusb library port, our XHCI model within VirtualBox, and
-the black-hole component.
-
-Practical considerations
-------------------------
-
-For users of the framework or Sculpt OS, the most notable change is that all
-USB clients use their own _devices_ ROM to react to device appearance and
-disappearance. No global information is required anymore. That means the
-addition of a new policy rule in the USB host-controller's configuration is
-sufficient to, e.g., let a device appear in a Linux guest. If the rule already
-exists, even the pure physical connect will result in the appearance of the
-device.
-
-Because one USB session can now control an arbitrary number of devices, the
-syntax of the policy rules for a USB host controller driver changed a bit:
-
-! <config>
-!   <policy label="usb_net">
-!     <device vendor_id="0x0424" product_id="0xec00"/>
-!   </policy>
-!   <policy label="usb_hid">
-!     <device class="0x3"/>
-!   </policy>
-!   <policy label="vm">
-!     <device name="usb-2-2"/>
-!     <device name="usb-2-4"/>
-!   </policy>
-! </config>
-
-As you might notice, there is no differentiation in the policy rules on the
-interface-level yet. In short, each device is still handled by only one
-driver. As a prerequisite to assign drivers to individual interfaces, drivers
-first have to become resilient against denied device-acquisition attempts.
-This is not the case for most ported drivers or virtualized guest OSes. Hence,
-even though the USB session API is now prepared for driving interfaces of one
-USB device by dedicated drivers, we decided against activating this feature on
-the policy level at the current time. Nonetheless, once a set of interface
-drivers gets in place, we can enable the added flexibility without touching
-the USB session API again.
-
-Sculpt OS
----------
-
-The outcome of this line of work is already present in
-[https://genodians.org/nfeske/2024-04-26-sculpt-os - Sculpt OS 24.04], which makes the
-[https://genode.org/documentation/articles/sculpt-24-04#Assignment_of_USB_devices_to_components - assignment of USB devices]
-to components intuitive and secure.
-
-
-On-target debugging using the GNU debugger (GDB)
-################################################
-
-The renovation of our debugging monitor in
-[https://genode.org/documentation/release-notes/23.08#Multi-component_debug_monitor - Genode 23.08]
-was driven by the vision of easy on-target debugging on Sculpt OS. Just
-imagine, any runtime component from applications over device drivers to VMMs,
-like VirtualBox, could be started with debugging optionally enabled. The key
-to make this vision come true is the debug monitor at the heart of the Sculpt
-runtime. All other missing ingredients for viable on-target debugging - above
-all a GDB front end - are introduced with this release.
-
-The _debug monitor_ component got introduced in version
-[https://genode.org/documentation/release-notes/23.08#Multi-component_debug_monitor - 23.08].
-It is a drop-in replacement for the init component with the added ability to
-control the execution and memory content of selected child components using
-the GDB remote serial protocol. On Sculpt, the debug monitor now acts as the
-runtime init component. The user decides which components are made available
-to debugger control with a check mark in the launcher menu before the
-component is started. If the component is selected for debugging, the monitor
-configuration part for this component is added to the Sculpt runtime
-configuration.
-
-The [https://www.sourceware.org/gdb/ - GDB] component is the user-facing part
-of the debugging experience. It presents a command line interface in a
-graphical terminal window and communicates with the debug monitor in the
-background. The user can enter GDB commands for inspecting and modifying the
-state of monitored components.
-
-In order to debug a component in a meaningful way, GDB usually needs to
-evaluate the executable files of the component and profits hugely from
-additional debug information like symbol names and source-code location
-information generated by the compiler. As this information can take up a lot
-of space, we decided to store it in separate debug info files shipped in
-dedicated _dbg_ depot packages since version
-[https://genode.org/documentation/release-notes/23.11#Debug_information_for_depot_binaries - 23.11].
-Two small support components help to make this information available to GDB at
-runtime:
-
-The _dbg_download_ component can be started by the user by checking the
-_download debug info_ option in the Sculpt launcher menu. It evaluates the
-Sculpt runtime configuration in the background and downloads any missing _dbg_
-archive content of monitored components into the depot.
-
-The _gdb_support_ component is started automatically together with GDB. It
-evaluates the Sculpt runtime configuration in the background and dynamically
-creates directories with symbolic links to the depot binaries and debug info
-files of monitored components in a RAM file system shared with GDB, and
-thereby allows GDB to access these files in a convenient way.
-
-[image on_target_gdb]
-
-With this setup in place, the user can debug multiple components at once
-and control the execution of threads on an individual basis thanks to GDB's
-_non-stop_ mode.
-Learn how to integrate and use GDB on Sculpt with our article and screencast
-video on [https://genodians.org/chelmuth/2024-05-17-on-target-debugging - Genodians.org].
-
-One noteworthy challenge discovered while testing on Sculpt was that GDB
-apparently was not prepared for the case that there are no initial inferiors
-and that the first inferior could appear spontaneously on the remote side
-instead of being actively started by GDB. We had to make some adaptations to
-the GDB source code to support this situation and some more adaptations might
-be necessary in the future, for example to update the output of the
-_info inferiors_ command when the first inferior appears.
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-Transition to the new audio interfaces introduced in 24.02
-==========================================================
-
-In Genode's
-[https://genode.org/documentation/release-notes/24.02#Revised_audio_infrastructure - February release],
-we introduced new audio 'Record' and 'Play' sessions intended to supersede the
-old 'Audio_in' and 'Audio_out' interfaces. In the time following up to the
-current release, we worked on integrating the new sessions into the existing
-components. In fact, they are already exercised in the most recent
-[https://genode.org/news/sculpt-os-release-24.04 - Sculpt release].
-
-As most prominently used by ported software, the VFS OSS plugin plays a vital
-role in interfacing with Genode's native audio stack. The already existing
-VFS plugin got renamed to _legacy_oss_ while the new one takes its place and
-is usable as a drop-in replacement. Existing users have to adapt the session
-routes accordingly or change their VFS configuration to make use of the
-legacy plugin, if the use of the new sessions is not yet desirable.
-
-In contrast to the old plugin, it is possible to configure the fragment size a
-client is allowed to use via its configuration and thereby enforce its latency
-requirements. The fragment size ranges from 2048 to 8192 bytes, which equals a
-period length of around 11.6 to 46.4 ms when using a sample rate of 44.1 kHz.
-The plugin leverages the ability of the _report_play_mixer_ to convert sample
-rates. However, to constrain the resource requirements of the plugin, it is
-limited from 8 kHz to 48 kHz, which covers a reasonable range. Please consult
-the _repos/gems/src/lib/vfs/oss/README_ file for more information.
-
-The _black_hole_ component gained additional support for providing the play
-and record sessions so that it is able to perform its role when using the new
-sessions. We also removed the custom audio subsystem from our SDL1.2 port in
-favor of using its own OSS back end, which brings it in line with our SDL2
-port.
-
-As there are no critical components left that exclusively use the old sessions
-directly, the way is paved to remove them. However, we keep the legacy audio
-sessions intact to give users time to migrate their components and become
-comfortable with the new interfaces.
-
-
-Improved timing stability
-=========================
-
-Our recent work on real-time audio processing moved the timing characteristics
-of the framework into focus. Low latency cannot be attained in the presence of
-high jitter. But in a component-based system carrying general-purpose
-workloads, jitter can be induced for many reasons including kernel scheduling,
-spontaneous high-priority events, or the interference between clients of
-shared services. The timer driver in particular is such a shared service.
-While analyzing the timer's behaviour under stress, we indeed observed
-unwelcome interference between timer clients. E.g., the stability of a
-waveform generated at a period of 5 milliseconds would be effected by
-otherwise unrelated spontaneous USB-HID events. Those observations motivated
-the following improvements:
-
-First, we simplified the timer implementation to make it dead-simple to
-understand and straight-forward to trace its behavior. The timer no longer
-relies on TSC-interpolated measurements but only on ground-truth values
-obtained from the timing device (or from the underlying kernel). Second, to
-improve accuracy at the client side, the timer no longer limits the time
-resolution when the current time is queried. The deliberate limiting of the
-time resolution is applied only to the triggering of timeouts in order to cap
-the timer's CPU load induced by its clients. Third, to limit the rate of
-inter-component communication, the timer batches the wake-up of clients that
-have timeouts closely clustered together. Combined, those measures reduced the
-cross-client interferences between timer clients comfortably below the level
-relevant for our synthetic test setup using audio periods of 5 ms. Note that
-such small periods are not generally usable in practice because real-world
-audio applications are subjected to additional sources of jitter.
-
-The improvements are in effect for the timers used on NOVA, the base-hw
-kernel, and the PIT-based timer as used on seL4, OKL4, and Pistachio. Linux,
-Fiasco.OC, and L4/Fiasco are not covered yet.
-
-
-Device drivers
-##############
-
-Linux-device-driver environment (DDE)
-=====================================
-
-Porting Linux drivers to Genode is a multi-staged process with the
-configuration of a minimal yet functional platform-specific Linux kernel as
-an essential step. The device support in this kernel is the baseline and
-reference for the final Genode driver. To simplify the testing of minimal
-kernel images, we introduced new run scripts for i.MX boards and PCs. Now, a
-plain execution of 'make run/pc_linux' or 'make run/imx_linux' runs Linux on
-the test target as known from Genode scenarios. In case of i.MX, a FIT image
-is generated, whereas we provide an i.PXE-bootable image for PCs. The run
-scripts integrate busybox into an initial RAM disk and, for i.MX, amend this
-image with _memtool_, a tool by Pengutronix to inspect all kind of memory
-under Linux (via _/dev/mem_).
-
-Furthermore, we address some deficiencies in DDE Linux with this release.
-We improved support for fine-grained, sub-millisecond timing by enabling
-high-resolution timers and attended to a long-standing pc_nic_drv link reset
-bug that manifested in some situations on some platforms only. For driver
-developers, we added the 'lx_emul_trace_msg()' function for the generation
-of low-overhead trace entries that can be used to debug timing-sensitive or
-high-traffic scenarios.
-
-
-Intel framebuffer and GPU driver
-================================
-
-An essential prerequisite for providing a GUI as Sculpt OS does, is having a
-driver for the graphics controller. In Genode, this task is split between the
-framebuffer driver and the GPU driver. Exposing these to a growing range of
-devices led to a few robustness and compatibility improvements for the Intel
-framebuffer/GPU drivers.
-
-In the context of the latest Sculpt release, we made the accounting of maximum
-framebuffer memory configurable. Previously, this was derived from the
-component's RAM quota, which implicitly limited the maximum display
-resolution. The separate configuration explicitly sets the maximum framebuffer
-memory by default to 64 MiB, which suffices for resolutions of at least
-3840x2160. The actual memory used by the component depends on the configured
-display resolution. If the RAM quota is depleted, the component will issue a
-resource request. The configuration follows the scheme established for the GPU
-driver with
-[https://genode.org/documentation/release-notes/24.02#Dynamic_aperture_handling_for_high_resolution_framebuffers - release 24.02].
-
-In this release, we also incorporated a vendor check in the Intel framebuffer
-driver in order to ensure that it only operates Intel devices. Our central
-platform driver typically hands out all VGA-class devices to the driver,
-including GPUs of other vendors. This caused issues on platforms with an
-additional Nvidia GPU for multiple users. Thanks to Alice Domage for this
-contribution.
-
-Furthermore, we fixed a few issues that popped up when test-driving Sculpt OS
-on the ZimaBlade. By doing this, we added support for Intel HD Graphics 500 to
-the Intel framebuffer/GPU drivers. This GPU can be found in various Intel
-Processors in the Pentium/Celeron N-series.
-
-
-Suspend/resume infrastructure
-=============================
-
-As planned in our [https://genode.org/about/road-map - road map], we
-integrated the current state of x86 suspend/resume as a feature into Sculpt
-OS. The sculpt manager got enhanced to drive the system state and manage the
-life cycle of driver components during suspend-resume cycles.
-The new
-[https://genode.org/documentation/articles/sculpt-24-04#System_power_control - power options]
-can be found in the _System_ menu once the ACPI support option is activated.
-
-[image sculpt_24_04_system_power]
-
-Non-stateful drivers are removed from the runtime before suspending and are
-restarted during resume, e.g., network drivers. Stateful drivers like NVME,
-AHCI, and GPU drivers participate cooperatively in the system states by
-stopping their processing and reporting their fulfillment. Currently, the USB
-host driver needs to be restarted forcefully on resume. To avoid data loss,
-the power suspend feature is not offered while a USB block device is in use.
-
-Additionally, during Sculpt integration, several drivers got enhanced. The
-acpica application now reflects the completion of the last action, which the
-sculpt manager monitors and incorporates into the system state machine. The PC
-platform driver saves and restores the IOMMU configurations before and after
-suspend. Additionally, the platform driver gained the ability to trigger the
-final suspend RPC to Genode's core. Furthermore, the Intel display driver now
-participates in the system state changes by switching off all connectors
-before suspend in order to reduce graphical noise on displays during the
-transition.
-
-
-Mesa updated to version 24.0.1
-==============================
-
-With the goal to add support for more recent Intel GPUs (Alder Lake+), we took
-the first step by updating our three-year-old Mesa 21 to version 24. Because
-Mesa is under heavy development, the effort to do so was more elaborate than
-anticipated. For the current release, we enabled all the previously supported
-GPUs, which are Intel Gen8 (Broadwell), Gen9 (Skylake up to Whiskey Lake),
-Gen12 (Tiger Lake) using the Iris Gallium driver, Vivante as found in i.MX8
-SoCs, and Mali on the PinePhone. There are still many improvements to be
-explored, like buffer life-time management, using Mesa's native build system
-(Meson) for simplifying future updates, testing Alder Lake, replacing softpipe
-with llvm for software rendering, and adding Vulkan support, to name a few.
-We are looking forward to tackle these topics in future Genode releases.
-
-
-Removed obsolete loader component and session interface
-=======================================================
-
-The loader was originally introduced in version
-[https://genode.org/documentation/release-notes/10.11#Qt4 - 10.11] as part of an
-early [https://genode.org/news/genode-live-demonstration-2010-11 - live CD].
-It later served the purpose of dynamically starting and stopping preconfigured
-subsystems. As of today, the latter use case has long been covered by the
-dynamically reconfigurable init component. The only substantial client of the
-loader remained to be the qpluginwidget in combination with the Arora web
-browser. But as the blending of plugins with websites never moved beyond a
-fancy tech demo and Arora was replaced by Falkon, the current release removes
-the now obsolete loader infrastructure.
-
-
-Libraries and applications
-##########################
-
-Consolidation of Tresor block encryptor and File Vault
-======================================================
-
-Genode [https://genode.org/documentation/release-notes/23.05#Revision_of_Genode_s_custom_block-encryption_infrastructure - 23.05]
-marked a big update of the core logic for block-data security and management
-behind the file vault. It replaced the former Ada/SPARK-based implementation
-called CBE with a C++-based, modernized library that we named _Tresor_. As a
-side effect of this endeavor, we improved testing and fixed many issues of the
-former approach. However, the tresor library also inherited some unwelcome
-traits from its predecessor. The CBE approach was shaped in many ways by the
-semantic restrictions imposed by SPARK and the tresor library had retained
-some of these at the expense of code redundancy. In addition, we had adopted a
-rather peculiar approach to execution flow that led to unforeseen
-implementation complexity down the road. In order to improve this situation,
-the current release comes with a comprehensive re-design of the tresor
-library, relieving it from legacy burdens, significantly shrinking the code
-base, and making it much easier to understand.
-
-Once warmed up with the topic, we stepped one level up in the block-encryption
-stack and continued reworking the tresor VFS plugin because it also suffered
-from over-complexity and redundancy. After finishing that, we noticed that the
-next higher layer - the File Vault - could also be improved in two ways:
-First, the file vault used to combine two unrelated tasks in one component:
-The logic for modeling typical user work-flows on the tresor VFS and the
-operation of a graphical user interface. We found that these are better
-assigned to separate components that work together via a narrow and
-well-defined interface. Second, the file vault used to operate directly on
-the low-level interface of the menu view component in order to drive its GUI
-instead of using the newer and far easier dialog API for this purpose.
-
-[image file_vault_gui]
-
-For the component that deals with the logic, we stayed with the name
-_file vault_ whereas the new front-end is the _file vault gui_.
-
-Putting all these changes together, the whole ecosystem around the tresor block
-encryption and the file vault becomes far more manageable and its code base
-has been cut in half while providing the same feature set as before:
-
-   component                    | 23.05 | 24.05 | difference
-  -----------------------------------------------------------
-  -----------------------------------------------------------
-   lib/tresor                   | 14374 |  5212 | -63%
-  -----------------------------------------------------------
-   lib/vfs/tresor               |  2728 |  1823 | -33%
-  -----------------------------------------------------------
-   lib/vfs/tresor_crypto        |  1162 |  1213 |
-  -----------------------------------------------------------
-   lib/vfs/tresor_trust_anchor  |  1800 |  1992 |
-  -----------------------------------------------------------
-   app/tresor_init              |   159 |    93 |
-  -----------------------------------------------------------
-   app/tresor_init_trust_anchor |   166 |   163 |
-  -----------------------------------------------------------
-   app/file_vault               |  5429 |  1256 | -76%
-  -----------------------------------------------------------
-   app/file_vault_gui           |     - |   617 |
-  -----------------------------------------------------------
-  -----------------------------------------------------------
-   total                        | 25818 | 12369 | -52%
-
-But the update is not only about cleaning up. We also consolidated the stack
-by, for instance, fixing and re-enabling asynchronous rekeying, implementing
-robust handling of corner-case configurations, patching several performance
-limitations, and further improving the test suite.
-
-Last but not least, the file vault received two handy usability enhancements.
-First, the new file-vault GUI is fully controllable via keyboard.
-The hotkeys are documented in _repos/gems/src/app/file_vault_gui/README_.
-Second, as an implication of separating GUI from logic, the text-based
-interface of the file vault became the canonical way to steer that component.
-In order to achieve that, the interface had to be extended to the full feature
-set, which has the welcome side effect of easing the combination of the file
-vault with alternative front ends. For instance, the file vault could now
-become an integrated part of the administrative user interface of Sculpt OS.
-The new interface is mostly backwards compatible (only the non-functional
-version attribute disappeared) and documented in
-_repos/gems/src/app/file_vault/README_.
-
-Despite the extensive overhaul, file vault version 24.05 remains compatible
-with old containers created via the 23.05 version and we also kept the
-structure and appearance of the new graphical front end close to that of the
-old version in order to make the transition as smooth as possible.
-
-
-VirtualBox network-throughput improvements
-==========================================
-
-The Uplink and NIC session interfaces provide means to batch several network
-packets before informing the other side to process the packets. The batching
-is crucial to achieve good network throughput and also to keep the CPU
-overhead per packet at a moderate level. Up to now, our ports of VirtualBox
-did not leverage this feature, which became noticeable on systems under high
-CPU load. By adding the batching of network packets to our VirtualBox ports,
-we were able to reduce the CPU load and achieve stable throughput
-measurements, which otherwise fluctuate more depending on other factors like
-scheduling.
-
-
-Seoul virtual machine monitor
-=============================
-
-Since the
-[https://genode.org/documentation/release-notes/24.02#Seoul_VMM - previous]
-release, the VMM received several improvements.
-
-Notably, the former global motherboard lock got replaced by fine-grained
-locking within each device model where appropriate. Thanks to the better CPU
-utilization, long-running work, for example compilation, now finishes earlier.
-The network binding got reworked and now reflects network link-state changes
-from the Genode interface into the guest VMs. The legacy audio-session binding
-got replaced by Genode's new Play interface.
-
-The so far unused ACPI model of the Seoul sources got enabled and adjusted
-to support so-called fixed ACPI events, e.g., power-button press event. On
-GUI window close, the event is now triggered and forwarded to the guest VM.
-Depending on the configuration of the guest, the VM may power down
-automatically, similar as done by our port of VirtualBox.
-
-Finally, a USB XHCI model powered by our qemu-usb library has been added to
-Seoul, which got developed during our recent
-[https://github.com/genodelabs/genode/issues/4989 - Hack'n'Hike] event.
-With this new model, USB devices can be passed through to the guest. It has
-been successfully tested with several USB storage, keyboard, and audio
-devices.
-
-
-SDL2 improvements
-=================
-
-We enhanced our SDL2 port by enabling more subsystems, improving its window
-handling, and adding support for its text-input API.
-
-This release adds preliminary support window resizing. It works well for some
-of the currently available ports but still has issues with others (especially
-those using an OpenGL context) as it depends to some degree on the component
-itself using the SDL2 library. As an additional feature, we added support for
-setting the initial window geometry via the '<initial>' node, e.g.:
-
-! <initial width="800" height="600"/>
-
-This allows for restricting the initial window size because otherwise the
-actual screen size will be used and that might be too large depending on the
-attached display.
-
-Support for using SDL2's text-input API has been enabled. Once the application
-enables text input, any key press that has a valid Unicode codepoint is sent
-as text input.
-
-
-Curl updated to version 8.7.1
-=============================
-
-We updated our cURL port to version 8.7.1 to support the use of
-elliptic-curve algorithms for TLS (CURLOPT_SSL_EC_CURVES).
-
-In setups where no service is employed to provide entropy, it might be
-necessary to increase the amount of statically configured entropy. Doubling
-the content of the '<inline>' VFS plugin as used in static configurations
-seems satisfactory. Furthermore, DNS resolving needs a configured '<pipe>'
-plugin to work properly. For an exemplary configuration, please look at the
-_repos/libports/run/fetchurl.inc_ run-script snippet.
-
-The 'fetchurl' component also gained a 'verbose' configuration option to
-enable verbose operations as a convenience feature to ease debugging.
-
-
-Platforms
-#########
-
-NOVA microhypervisor
-====================
-
-Some of the command-line options changed. The 'iommu' option is now split up
-into 'iommu_amd' and 'iommu_intel', so that they may be enabled/disabled
-separately. The 'novga' option turned into 'vga' since it is unused nowadays.
-The tagged TLB feature for virtual machines is now enabled by default.
-
-The kernel now supports the 'mwait' instruction besides the 'hlt' instruction,
-which can be used to give hints to the CPU to enter deeper sleep states.
-The feature is off by default and can be utilized via the 'Pd::system_control'
-interface.
-
-
-Build system and tools
-######################
-
-Goa SDK
-=======
-
-Aligned with the Sculpt release, the Goa tool has been updated with the
-corresponding depot archive versions for Sculpt 24.04. This also involved
-adding support for the new audio play and record sessions.
-
-The _Goa testbed_ package and preset have been updated accordingly so that
-an out-of-the-box Sculpt 24.04 lends itself as a
-[https://genode.org/documentation/release-notes/24.02#Sculpt_OS_as_remote_test_target_for_the_Goa_SDK - remote test target for Goa].

doc/release_notes/24-08.txt

@@ -1,451 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 24.08
-              ===============================================
-
-                               Genode Labs
-
-
-
-Genode 24.08 puts emphasis on the tracking of the supported 3rd-party software
-and consolidation work. It features the Qt6 application framework in addition
-to the time-tested Qt5, consistently updates all Linux-based components and
-PC device drivers from Linux version 6.1 to version 6.6.47, and updates Mesa
-to version 24.0.8. The consolidation work revisits the framework's base and
-GUI interfaces with respect to C++20 style, the move away from exception-based
-error handling, and the use of strict types.
-
-Combining Genode's recent advances of
-[https://genode.org/documentation/release-notes/24.05#On-target_debugging_using_the_GNU_debugger__GDB_ - on-target debugging]
-with the
-[https://genode.org/documentation/release-notes/23.08#Goa_tool_gets_usability_improvements_and_depot-index_publishing_support - Goa SDK],
-the release introduces remote debugging via Goa (Section [Debugging]). Further
-topics of version 24.08 range from enhanced board support for i.MX-based
-devices (Section [Improvements for NXP's i.MX family]), over the exploration
-of AVX on x86 (Section [NOVA microhypervisor]), to steady improvements of
-Genode's custom microkernel (Section [Execution on bare hardware (base-hw)]).
-
-
-Base framework and OS-level infrastructure
-##########################################
-
-Reduced reliance on the C++ exception mechanism
-===============================================
-
-In [https://genode.org/documentation/release-notes/21.11#New_pattern_for_C___error_handling - version 21.11],
-we introduced the
-[https://genode.org/documentation/genode-foundations/24.05/api/Fundamental_types.html#Exception-less_error_handling - Attempt]
-utility as an alternative to exception-based error handling. While gradually
-applying this pattern, in particular for newly introduced interfaces, we
-observed our code becoming more rigid and concrete, leaving no condition
-unconsidered. Given this added assurance, we ultimately decided to remove
-the reliance on C++ exceptions from the base framework over time. The current
-release takes a huge leap in this direction.
-
-:base/id_space.h:
-  A new 'Id_space::apply' overload takes a second functor 'missing_fn' as
-  argument, which is called whenever the lookup fails. It thereby allows the
-  use of the 'Id_space' utility without 'Unknown_id' exceptions.
-
-:util/xml_node.h:
-  The two 'Xml_node::attribute' accessors have been removed along with the
-  'Nonexistent_attribute' exception. Attributes are generally accessed via the
-  'attribute_value' method, which handles the case via a default value.
-
-:Core RPC interfaces:
-  Exceptions have been entirely removed from the RPC interfaces provided by
-  the core component, namely 'Trace', 'Pd', 'Cpu', 'Rm', and 'Region_map'.
-
-  While touching these interfaces, we took the opportunity for modernization
-  and consolidation of both the interfaces and their implementations. E.g.,
-  core's trace service received a welcome facelift, e.g., the former use of
-  basic types got replaced by dedicated types.
-
-  The revised 'Region_map' interface uses an 'Attr' compound struct for
-  specifying arguments to the 'attach' operation, which makes the intent of
-  client code more obvious. The operation returns a 'Range' instead of a
-  'Local_addr' now. The 'Region_map::State' type got renamed to 'Fault'.
-
-:base/child.h:
-  The 'Child_policy::Nonexistent_id_space' exception has been removed by
-  making the 'server_id_space' mandatory for each policy. The former
-  'Child::Process' and 'Child::Process::Loaded_executable' classes got
-  replaced by class functions that return failure conditions as return
-  values, eliminating the use of C++ exceptions by the child framework.
-
-The overall ambition of cutting back the use of C++ exceptions is not limited
-to the base framework but can be observed for critical components as well.
-In particular, the NIC router received a profound rework in this respect.
-
-
-Cultivation of C++20 programming style
-======================================
-
-[https://genode.org/documentation/release-notes/23.05#New_tool_chain_based_on_GCC_12.3__C__20_enabled_by_default - One year ago],
-we enabled C++20 as default. With the current release, we took the chance to
-update the codebase according to this version of the standard.
-
-:C++20 function template syntax:
-  The 'auto' keyword can be used in many places where template arguments had
-  to be declared manually. We updated all sources of the base framework
-  accordingly.
-
-:Using 'using' instead of 'typedef':
-  C-style type aliases are no longer used within the framework.
-
-:util/geometry.h:
-  The header has been moved from the os repository to the base repository.
-  'Point', 'Area', and 'Rect' have been turned into plain compound types,
-  making 'x', 'y', 'w', 'h', 'at', and 'area' accessible without a method
-  call. 'Rect' is now represented as a tuple of 'Point' and 'Area', which is
-  the most common form of initialization. The companion utilities have been
-  updated ('constexpr', eliminating out parameters) as well.
-
-:util/color.h:
-  The 'Color' type has been converted from a class to a POD type by replacing
-  the constructors by the named create functions 'rgb', 'clamped_rgb', and
-  'clamped_rgba'. This enables the initialization of color values using the
-  '{ .r = ... }' syntax and makes the type usable in const expressions. The
-  change also narrows the type for the color components and alpha values to
-  'uint8_t'. So possible integer overflows of computed values are detected
-  by '-Wconversion'.
-
-
-Tightened GUI-session interface
-===============================
-
-On our [https://genode.org/about/road-map - road map], we anticipated
-intensive work on user-facing topics, many being related to graphical user
-interfaces. While approaching these topics, we sensed that the clean
-implementation of our ideas would benefit from a revisit of the framework's
-existing GUI infrastructure, in particular the GUI-session interface as
-provided by the nitpicker GUI server and the window manager. Note that we
-barely touched this corner of the framework in the past ten years since
-version
-[https://genode.org/documentation/release-notes/14.08#New_GUI_architecture - 14.08].
-The changes are as follows.
-
-* The 'Gui::Session::session_control' RPC function got removed because its
-  functionality has long been superseded by the window manager and layouter.
-
-* The interfaces and components received a thorough coding-style update,
-  embracing C++20, avoiding plain pointers, using 'Attr' structs for passing
-  attributes, removing the notion of invalid handles/IDs, replacing basic
-  types by dedicated types, and removing the use of C++ exceptions.
-
-* The out-of-RAM and out-of-caps conditions are now consistently handled by
-  the 'Gui::Connection', which does no longer inherit the 'Gui::Session'
-  interface and can thereby introduce tailored result types.
-
-* The creation of top-level views and child views are now two distinct
-  operations ('view' and 'child_view').
-
-* The access of the subsumed framebuffer and input interfaces is now
-  mediated by the plain public members 'Connection::framebuffer' and 'input'.
-  This simplifies the client-side code. E.g., '_gui.input()->pending()'
-  becomes '_gui.input.pending()'.
-
-* Corner cases of view-stacking operations are now expressed as dedicated
-  commands. The new stacking commands are FRONT, BACK, FRONT_OF, and BEHIND_OF.
-
-* View handles are managed as 'Id_space' and hence named view IDs now. The
-  allocation of view IDs has been moved from the server side to the client,
-  which gives clients more flexibility and reduces the surface of possible
-  error conditions between client and server. To ease the client-side ID
-  management, the 'Gui::Connection' hosts a 'view_ids' ID space for optional
-  use. E.g., the new 'Top_level_view' class uses this ID space for ID
-  allocation. This class accommodates the most typical use case of opening a
-  single window.
-
-* The creation of new views accepts initial view attributes now, which
-  accommodate typical client use cases with less code.
-
-_As a note of caution, this line of work will continue over the course of the_
-_next release cycle. The GUI-related APIs of the framework are expected to_
-_undergo further changes during that time._
-
-
-Fostered consistency of naming
-==============================
-
-Within our code base, we are ardent about consistency. However, two relics
-from the infancy of the project remained standing out like sore thumbs. First,
-the '_drv' suffix of driver executables remained at odds with our established
-[https://genode.org/documentation/developer-resources/conventions - style]
-of naming things without artificial abbreviations. Second, the plural naming
-of the _<repo>/src/drivers/_ directory nagged us by being inconsistent with
-the sibling directories _test/_, _app/_, _server/_. The current release
-rectifies both inconsistencies. The '_drv' suffix has been dropped and the
-directory has been renamed to _driver/_.
-
-
-Device drivers
-##############
-
-Linux device-driver environment (DDE)
-=====================================
-
-We last adapted Linux DDE for kernel 6.1 in May/August 2023. According to
-our plan of approximately one update per year, it was time to roll up our
-sleeves for the adaption to Linux 6.6 LTS and ready our driver base for
-future (especially PC) platforms. With this release, we limited our efforts
-to the emulation library itself as well as virt_linux and pc_linux driver
-ports.
-
-Thus, from now on, PC platforms use Linux driver sources of kernel version
-6.6.47 for USB host controllers and devices, Wifi and Ethernet adapters,
-Intel display, lxip TCP/IP protocols, and wireguard. Non-x86 platforms were
-updated for USB devices and network protocols only, but will be adapted in
-future releases step-by-step. All drivers work as drop-in-replacements of
-older versions with respect to integration and configuration.
-
-Our Wifi driver port got amended by an online quality update concerning the
-currently established connection, which can be enabled by the configuration
-attribute 'update_quality_interval'. With this feature, user interfaces are
-enabled to reflect connection-quality changes almost instantly. Additionally,
-we added support for Intel AX200/9560 wireless adapters and restored support
-for Wifi devices found in Thinkpad T430 notebooks.
-
-During this release cycle, we analyzed a noticeable network throughput drop
-resp. CPU load increase when using the
-[https://github.com/genodelabs/genode/issues/5151 - PC Ethernet driver].
-We eventually traced the effect to runtime overhead originating from our DDE
-memory allocator. The positive impact of a simple allocation-cache
-implementation confirmed our suspicion veritable. Hence, we replaced our
-custom allocator by the Linux kernel-internal SLUB allocator that is based
-on page/folio allocation. The folio API is well hidden in the kernel
-internals, still in flux, and offers only incomplete (resp. outdated)
-documentation, which required quite a bit of research efforts reading and
-understanding the kernel's implementation.
-
-In the end, we improved our emulation implementation sufficiently and managed
-to get the PC NIC driver to work robustly with gigabit performance and with
-CPU load reduced by 25-40% on Intel Kaby/Tiger Lake notebooks.
-
-
-Platform driver
-===============
-
-During ACPI suspend, the PCI bridges in the system may forget their PCI
-configuration. Hence on resume, this configuration needs to be restored to
-render all PCI devices behind the bridge usable again. With this release, we
-added support to the pci_decode component to report all relevant information,
-which is then picked up by the platform driver after an ACPI resume to
-re-configure the used PCI bridges. This change enables the successful
-restart of the Wifi driver after resume on many platforms.
-
-
-Improvements for NXP's i.MX family
-==================================
-
-The current release comprises a lot of updates and additional support for the
-i.MX family of devices.
-
-First of all, we have updated all existent Linux driver ports to Linux kernel
-version 6.1.20. In detail, drivers for the Freescale Ethernet Device (FEC) for
-ARMv7 and ARMv8, the display management for the i.MX 8M Quad EVK and the MNT
-Reform 2, as well as the SD-card Host Controller for the same two boards got
-refreshed.
-
-Alice Domage of Gapfruit AG contributed outstanding work to enable platform
-support for the i.MX 8M Plus SoC and Compulab's IOT Gateway, which is based on
-it. Besides clock, powering, and reset support by a platform driver specific
-to this SoC, support is now available for both Ethernet cards (FEC and ST
-Microelectronics' STMMAC), SD-card host controller, I2C, and GPIO.
-
-Genode's custom kernel supports two more boards now, namely the F&S Embedded
-armStone Starterkit and MNT Pocket Reform. Both are using the i.MX 8M Plus SoC
-mentioned above. The support is currently limited to the very basics, and no
-peripherals apart from CPU and timer are integrated yet.
-
-For the fine-grained control of GPIO pins, release
-[https://genode.org/documentation/release-notes/21.11#Pin_I_O_session_interfaces - 21.11],
-introduced the pin I/O session interfaces, superseding the older 'Gpio'
-session interface. So far, however, our driver for the GPIO controller as
-present on all i.MX SoC's merely supported the old interface. With this
-release, we introduce a pin driver implementing the favored pin I/O session
-interface instead. All occurrences in packages and run-scripts under Genode's
-umbrella use the new driver now, which can be found under _src/driver/pin/imx_
-within the genode-imx repository. The old driver and the 'Gpio' session
-interface are still existent. But now, as there is no hard dependency or
-necessity for it anymore, we mark the old driver as well as the 'Gpio' session
-interface as deprecated.
-
-Finally, we moved all remaining i.MX specific parts out of Genode's main
-repository into the [https://github.com/genodelabs/genode-imx - genode-imx]
-repository to be consistent with our recent approach of vendor-specific
-external repositories.
-
-
-Libraries and applications
-##########################
-
-Qt6 application framework
-=========================
-
-With this release, we started updating the Qt application framework from Qt5
-to Qt6 by adding an initial port of Qt 6.6.2, covering the _qtbase_,
-_qtdeclarative_, _qtshadertools_, and _qtsvg_ modules. We are planning to
-support the _qtwebengine_ module as well in the near future, which will remove
-the dependency from Python 2 and provide us with a more recent Chromium engine
-for the Falkon and Morph web browsers.
-
-We also improved the Qt build process for both Qt6 and Qt5 by making sure that
-Qt libraries are only built when needed and stub libraries generated from
-symbol files are used otherwise.
-
-The Qt6 port uses updated host tools, which need to be built with the
-_tool/tool_chain_qt6_ script. Please note that Qt6 requires CMake version 3.19
-or higher to build successfully.
-
-
-Mesa version 24.0.8
-===================
-
-With release
-[https://genode.org/documentation/release-notes/24.05#Mesa_updated_to_version_24.0.1 - 24.05],
-we updated Mesa to major version 24. During the past few months, we improved
-the memory allocation and synchronization for Intel's Iris driver and as a
-side effect updated Mesa to version 24.0.8.
-
-
-Platforms
-#########
-
-Execution on bare hardware (base-hw)
-====================================
-
-Under the hood of Genode's custom kernel, the way how CPU-local memory is
-arranged changed fundamentally. The kernel's virtual memory layout now
-comprises a CPU area. Each CPU has its own slot within this area, containing
-kernel stack, CPU object data resp. all CPU-local data. This change is
-transparent to most Genode developers. It was motivated to ease CPU detection
-and bootstrapping at run time, for kernel stack overflow detection, and for
-increasing the kernel's flexibility regarding multi-core hardware.
-
-
-NOVA microhypervisor
-====================
-
-The kernel received support to handle the x86 CPU FPU extension
-[https://de.wikipedia.org/wiki/Advanced_Vector_Extensions - AVX], which is a
-family of SIMD instruction extensions used for optimized implementations of
-mathematical algorithms, e.g., it is used in multimedia applications. In
-principle, the kernel has to detect the available AVX versions, e.g., AVX,
-AVX-2, AVX-512. Depending on the version, it has to save and restore
-additional FPU state during thread switching. Besides the general
-availability to Genode applications, the Seoul VMM has become the first user
-of the feature. The VMM now announces the AVX feature to the guest VMs, so
-that the guest kernel can enable it and guest user applications can utilize
-it, e.g., for web browser and video encoding/decoding use-cases. The feature
-got tested with the Seoul VMM on Intel and AMD systems.
-
-Additionally, we adapted the core component to support Intel SoCs with E-Core
-only CPUs, which were formerly named Intel Atom and are nowadays branded as
-Intel N-Series CPUs.
-
-Finally, the NOVA kernel now supports the freeing of vCPU related data
-structures during VM destruction, got optimized to reduce resource overhead
-during cross CPU IPC and improved VM MSR exit handling.
-
-
-Build system and tools
-######################
-
-Improved reproducibility
-========================
-
-The demand for reproducible builds has been increasing during the past few
-years. The main hindrance that makes builds unreproducible are timestamps. On
-Genode, especially components that produce TAR files suffered from this
-limitation, since the date of the archived data was set to the time of
-archiving. To avoid this issue, we introduced a customizable global TAR_OPT in
-Genode's build system that sets the date of the archived files to the date of
-the epoch and the user/group to one. As a starting point, we added the TAR_OPT
-to the Qt-build process while other targets will incrementally follow.
-
-Additionally, we enabled our Rump-kernel port to be reproducible.
-
-
-Goa SDK
-=======
-
-Debugging
-~~~~~~~~~
-
-After the addition of on-target debugging on Sculpt OS in
-[https://genode.org/documentation/release-notes/24.05#On-target_debugging_using_the_GNU_debugger__GDB_ - Genode 24.05],
-it was about time to equip [https://github.com/genodelabs/goa - Goa] with
-debugging support as well. For this purpose, the tool received an optional
-'--debug' command-line switch, which instructs Goa to consider
-[https://genode.org/documentation/release-notes/23.11#Debug_information_for_depot_binaries - dbg archives]
-in its download, export and publish steps.
-
-When provided with this switch on 'goa run', the tool also creates a
-_<project-name>.gdb_ file in the project's _var/_ directory. This file contains
-initialization commands for the GNU debugger (GDB) and can be passed to GDB
-via the '--command' argument.
-
-[image goa_gdb_sculpt]
-
-The _Goa testbed_ package and preset have been updated accordingly to make use
-of our debug monitor. The figure illustrates how Goa interoperates with the
-Goa testbed. Sculpt's default NIC router configuration now comprises an
-additional _gdb_ domain that is intended to accommodate a single client to
-which the router forwards port 9999 of the _uplink_ domain. This is intended
-for making the testbed's debug monitor available as a remote GDB target. Note
-that these changes will become effective with the next Sculpt release in
-October. In the meantime, you may cherry-pick the
-[https://github.com/genodelabs/genode/commit/aeb42b0983143e6fe0a01f7f5316612709da1a9d - corresponding commit].
-
-Along with debugging support, Goa also received a '--with-backtrace' switch and
-a 'backtrace' command. The former instructs the tool to preserve frame-pointer
-information by supplying the '-fno-omit-frame-pointer' flag to GCC. The
-'goa backtrace' command is a shortcut for 'goa run --debug --with-backtrace'
-that additionally passes the log output to our
-[https://genode.org/documentation/release-notes/24.02#Convenient_parsing_of_backtraces - backtrace tool].
-
-For detailed instructions, please refer to the corresponding
-[https://genodians.org/jschlatow/2024-07-31-goa-gdb - Genodians article].
-
-
-Meson build system
-~~~~~~~~~~~~~~~~~~
-
-Projects like Qemu, glib, and Mesa have switched to the Python-based
-[https://mesonbuild.com - Meson] build system. Mesa, for example, produces a
-large number of generated C/C++ files using Meson features. In order to ease
-future porting effort of Meson-based projects to Genode, we have added basic
-support for this build system to Goa.
-
-A Meson project can be built and executed like any other Goa-supported build
-system with the addition that there can be a _meson_args_ file (analogously to
-_cmake_args_ for CMake) where additional arguments can be passed to the meson
-command. Otherwise, Goa will look for a _meson.build_ file in the _src_
-directory, which identifies the project's build system as Meson.
-
-As a simple test, you can check out the _hello_meson_ example in the _examples_
-directory of Goa.
-
-At the current stage, only binary targets for the x86_64 architecture are
-supported by Goa/Meson. Shared libraries and ARM support will be addressed
-next.
-
-
-Rust & Cargo
-~~~~~~~~~~~~
-
-From Rust 1.77 onward, the binary distribution of the _std_ library
-('x86_64-unknown-freebsd') assumes that the underlying OS kernel supports
-thread-local storage via the FS segment register on x86. As Genode does not
-provide a TLS area via FS, TLS accesses by the library would end up in invalid
-memory, which renders the binary version of the std library unusable on
-Genode. In response, we have implemented a custom Genode target profile for
-Rust, which allows us to still leverage the FreeBSD port of Rust's standard
-library while using the _emulated_ TLS model. In order to compile the parts of
-the std library used by an application for the custom profile, we have moved
-to using a _nightly_ Rust tool chain. For detailed instructions for setting up
-the tool chain, head over to the
-[https://genodians.org/atopia/2024-08-27-building-rust-with-a-custom-profile - blog post]
-at Genodians.org.

doc/release_notes/24-11.txt

@@ -1,579 +0,0 @@
-
-
-              ===============================================
-              Release notes for the Genode OS Framework 24.11
-              ===============================================
-
-                               Genode Labs
-
-
-
-During the discussion of this year's road-map roughly one year ago, the
-usability concerns of Sculpt OS stood out.
-Besides suspend/resume, which we addressed
-[https://genode.org/documentation/release-notes/24.05#Suspend_resume_infrastructure - earlier this year],
-multi-monitor support ranked highest on the list of desires. We are more than
-happy to wrap up the year with the realization of this feature.
-Section [Multi-monitor support] presents the many facets and outcomes of this
-intensive line of work.
-
-Over the course of 2024, our Goa SDK has received tremendous advances, which
-make the development, porting, debugging, and publishing of software for
-Genode - and Sculpt OS in particular - a breeze.
-So far however, the learning curve for getting started remained rather steep
-because the underlying concepts largely deviate from the beaten tracks known
-from traditional operating systems. Even though there is plenty of
-documentation, it is rather scattered and overwhelming.
-All the more happy we are to announce that the current release is accompanied
-by a new book "Genode Applications" that can be downloaded for free and
-provides a smooth gateway for application developers into the world of Genode
-(Section [New "Genode Applications" book]).
-
-Regarding hardware-related technical topics, the release focuses on the
-ARM-based i.MX SoC family, taking our ambition to run Sculpt OS on the MNT
-Pocket Reform laptop as guiding theme. Section [Device drivers and platforms]
-covers our driver and platform-related work in detail.
-
-
-New "Genode Applications" book
-##############################
-
-Complementary to our _Genode Foundations_ and _Genode Platforms_ books, we have
-been working on a new book that concentrates on application development.
-_Genode Applications_ centers on the Goa SDK that we introduced with
-[https://genode.org/documentation/release-notes/19.11#New_tooling_for_bridging_existing_build_systems_with_Genode - Genode 19.11]
-and which has seen significant improvements over the past year
-([https://genode.org/documentation/release-notes/23.08#Goa_tool_gets_usability_improvements_and_depot-index_publishing_support - 23.08],
-[https://genode.org/documentation/release-notes/24.02#Sculpt_OS_as_remote_test_target_for_the_Goa_SDK - 24.02],
-[https://genode.org/documentation/release-notes/24.08#Goa_SDK - 24.08]).
-
-: <div class="visualClear"><!-- --></div>
-: <p>
-:  <div style="clear: both; float: left; margin-right:20px;">
-:   <a class="internal-link" href="https://genode.org">
-:    <img class="image-inline" src="https://genode.org/documentation/genode-applications-title.png">
-:   </a>
-:  </div>
-: </p>
-
-The book intends to provide a beginner-friendly starting point for application
-development and porting for Genode and Sculpt OS in particular. It starts off
-with a getting-started tutorial for the Goa tool, and further recapitulates
-Genode's architecture and a subset of its libraries, components, and
-conventions such as the C runtime, VFS, NIC router, and package management.
-With these essentials in place, the book is topped off with instructions for
-application debugging and a collection of advanced tutorials.
-
-Aligned with the release of Sculpt 24.10, we updated the Goa tool with the
-corresponding depot archive versions. Furthermore, the Sculpt-integrated and
-updated _Goa testbed_ preset is now prepared for remote debugging.
-
-: <div class="visualClear"><!-- --></div>
-
-:First revision of the Genode Applications document:
-
-  [https://genode.org/documentation/genode-applications-24-11.pdf]
-
-
-Multi-monitor support
-#####################
-
-Among the users of the Genode-based Sculpt OS, the flexible use of multiple
-monitors was certainly the most longed-after desire raised during our public
-road-map discussion roughly one year ago. We quickly identified that a
-profound solution cannot focus on piecemeal extensions of individual
-components but must embrace an architectural step forward. The step turned
-out being quite a leap.
-In fact, besides reconsidering the roles of display and input drivers in
-[https://genode.org/documentation/release-notes/20.08#The_GUI_stack__restacked - version 20.08],
-the GUI stack has remained largely unchanged since
-[https://genode.org/documentation/release-notes/14.08#New_GUI_architecture - version 14.08].
-So we took our multi-monitor ambitions as welcome opportunity to incorporate
-our experiences of the past ten years into a new design for the next ten
-years.
-
-
-Tickless GUI server and display drivers
-=======================================
-
-Up to now, the nitpicker GUI server as well as the display drivers used to
-operate in a strictly periodic fashion. At a rate of 10 milliseconds, the GUI
-server would route input events to the designated GUI clients and flush
-graphical changes of the GUI clients to the display driver.
-This simple mode of execution has benefits such as the natural ability of
-batching input events and the robustness of the GUI server against overload
-situations. However, in Sculpt OS, we observed that the fixed rate induces
-little but constant load into an otherwise idle system, rendering
-energy-saving regimes of modern CPUs less effective than they could be.
-This problem would become amplified in the presence of multiple output channels
-operating at independent frame rates. Moreover, with panel self-refresh
-support of recent Intel graphics devices, the notion of a fixed continuous
-frame rate has become antiquated.
-
-Hence, it was time to move to a tickless GUI-server design where the GUI
-server acts as a mere broker between events triggered by applications (e.g.,
-pushing pixels) and drivers (e.g., occurrence of input, scanout to a display).
-Depending on the behavior of its clients (GUI applications and drivers alike),
-the GUI server notifies the affected parties about events of interest but
-does not assert an active role.
-
-For example, if a display driver does not observe any changed pixels for 50
-ms, it goes to sleep. Once an application updates pixels affecting a display,
-the GUI server wakes up the respective display driver, which then polls the
-pixels at a driver-defined frame rate until observing when the pixels remain
-static for 50 ms. Vice versa, the point in time when a display driver requests
-updated pixels is reflected as a sync event to GUI applications visible on
-that display, enabling such applications to synchronize their output to the
-frame rate of the driver. The GUI server thereby asserts the role of steering
-the sleep cycles of drivers and applications. Unless anything happens on
-screen, neither the GUI server nor the display driver are active. When two
-applications are visible on distinct monitors, the change of one application
-does not induce any activity regarding the unrelated display. This allows for
-scaling up the number of monitors without increasing the idle CPU load.
-
-This change implies that the former practice of using sync signals as a
-time source for application-side animation timing is no longer viable.
-Sync signals occur only when a driver is active after all. GUI applications
-may best use sync signals for redraw scheduling but need to use a real time
-source as basis for calculating the progress of animations.
-
-
-Paving the ground for tearing-free motion
-=========================================
-
-Tearing artifacts during animations are rightfully frowned upon. It goes
-without saying that we strive to attain tearing-free motion in Genode. Two
-preconditions must be met. First, the GUI server must be able to get hold
-of a _consistent_ picture at any time. Second, the flushing of the picture
-to the display hardware must be timed with _vsync_ of the physical display.
-
-Up to now, the GUI stack was unable to meet the first precondition by design.
-If the picture is composed of multiple clients, the visual representation of
-each client must be present in a consistent state.
-The textures used as input of the compositing of the final picture are buffers
-shared between server and client. Even though clients traditionally employ
-double-buffering to hide intermediate drawing states, the final back-to-front
-copy into the shared buffer violated the consistency of the buffer during
-the client-side copy operation - when looking at the buffer from the server
-side. To overcome this deficiency, we have now equipped the GUI server with
-atomic blitting and panning operations, which support atomic updates in two
-fashions.
-
-_Atomic back-to-front blitting_ allows GUI clients that partially update their
-user interface - like regular application dialogs - to implement double
-buffering by placing both the back buffer and front buffer within the GUI
-session's shared buffer and configuring a view that shows only the front
-buffer. The new blit operation ('Framebuffer::Session::blit') allows the client
-to atomically flush pixels from the back buffer to the front buffer.
-
-_Atomic buffer flipping_ allows GUI clients that always update all pixels -
-like a media player or a game - to leverage panning
-('Framebuffer::Session::panning') to atomically redirect the displayed pixels to
-a different portion of the GUI session's shared buffer without any copy
-operation needed. The buffer contains two frames, the displayed one and the
-next one. Once the next frame is complete, the client changes the panning
-position to the portion containing the next frame.
-
-Almost all GUI clients of the Genode OS framework have been updated to use
-these new facilities.
-
-The vsync timing as the second precondition for tearing-free motion lies in
-the hands of the display driver, which can in principle capture pixel updates
-from the GUI server driven by vsync interrupts. In the presence of multiple
-monitors with different vsync rates, a GUI client may deliberately select
-a synchronization source ('Framebuffer::Session::sync_source'). That said,
-even though the interfaces are in place, vsync timing is not yet provided by
-the current display drivers.
-
-
-Mirrored and panoramic monitor setups
-=====================================
-
-A display driver interacts with the nitpicker GUI server as a capture client.
-One can think of a display driver as a screen-capturing application.
-Up until now, the nitpicker GUI server handed out the same picture to each
-capture client. So each client obtained a mirror of the same picture. By
-subjecting each client to a policy defining a window within a larger panorama,
-a driver creating one capture session per monitor becomes able to display the
-larger panorama spanning the connected displays. The assignment of capture
-clients to different parts of the panorama follows Genode's established
-label-based policy-selection approach as explained in the
-[https://github.com/genodelabs/genode/blob/master/repos/os/src/server/nitpicker/README - documentation]
-of the nitpicker GUI server.
-
-Special care has been taken to ensure that the pointer is always visible. It
-cannot be moved to any area that is not captured. Should the only capture
-client displaying the pointer disappear, the pointer is warped to the center
-of (any) remaining capture client.
-
-A mirrored monitor setup can in principle be attained by placing multiple
-capture clients at the same part of nitpicker's panorama. However, there is
-a better way: Our Intel display-driver component supports both discrete and
-merged output channels. The driver's configuration subsumes all connectors
-listed within a '<merge>' node as a single encompassing capture session at the
-GUI server. The mirroring of the picture is done by the hardware. Each
-connector declared outside the '<merge>' node is handled as a discrete capture
-session labeled after the corresponding connector. The driver's
-[https://github.com/genodelabs/genode/blob/master/repos/pc/src/driver/framebuffer/intel/pc/README - documentation]
-describes the configuration in detail.
-
-
-Sculpt OS integration
-=====================
-
-All the changes described above are featured in the recently released
-Sculpt OS version 24.10, which gives the user the ability to attain mirrored
-or panoramic monitor setups or a combination thereof by the means of manual
-configuration or by using interactive controls.
-
-[image sculpt_24_10_intel_fb]
-
-You can find the multi-monitor use of Sculpt OS covered by the
-[https://genode.org/documentation/articles/sculpt-24-10#Multi-monitor_support - documentation].
-
-
-Revised inter-component interfaces
-==================================
-
-Strict resource partitioning between GUI clients
-------------------------------------------------
-
-Even though Genode gives server components the opportunity to strictly operate
-on client-provided resources only, the two prominent GUI servers - nitpicker
-and the window manager (wm) - did not leverage these mechanisms to full
-extent. In particular the wm eschewed strict resource accounting by paying out
-of its own pocket. This deficiency has been rectified by the current release,
-thereby making the GUI stack much more robust against potential resource
-denial-of-service issues. Both the nitpicker GUI server and the window manager
-now account all allocations to the resource budgets of the respective clients.
-This change has the effect that GUI clients must now be equipped with the
-actual cap and RAM quotas needed.
-
-Note that not all central parts of the GUI stack operate on client-provided
-resources. In particular, a window decorator is a mere client of the window
-manager despite playing a role transcending multiple applications. As the
-costs needed for the decorations depend on the number of applications present
-on screen, the resources of the decorator must be dimensioned with a sensible
-upper bound. Fortunately, however, as the decorator is a plain client of the
-window manager, it can be restarted, replaced, and upgraded without affecting
-any application.
-
-
-Structured mode information for applications
---------------------------------------------
-
-Up to now, GUI clients were able to request mode information via a plain
-RPC call that returned the dimensions and color depth of the display.
-Multi-monitor setups call for more flexibility, which prompted us to
-replace the mode information by XML-structured information delivered as
-an 'info' dataspace. This is in line with how meta information is handled
-in other modern session interfaces like the platform or USB sessions.
-The new representation gives us room to annotate information that could
-previously not be exposed to GUI clients, in particular:
-
-* The total panorama dimensions.
-* Captured areas within the panorama, which can be used by multi-monitor
-  aware GUI clients as intelligence for placing GUI views.
-* DPI information carried by 'width_mm' and 'height_mm' attributes.
-  This information is defined by the display driver and passed to the GUI
-  server as 'Capture::Connection::buffer' argument.
-* The closed state of a window interactively closed by the user.
-
-Note that the window manager (wm) virtualizes the information of the nitpicker
-GUI server. Instead of exposing nitpicker's panorama to its clients, the wm
-reports the logical screen hosting the client's window as panorama and the
-window size as a single captured rectangle within the panorama.
-
-
-Mouse grabbing
---------------
-
-Since the inception of the nitpicker GUI server, its clients observed absolute
-pointer positions only. The GUI server unconditionally translated relative
-mouse-motion events to absolute motion events.
-To accommodate applications like games or a VM emulating a relative pointer
-device, we have now extended the GUI server(s) with the ability to selectively
-expose relative motion events while locking the absolute pointer position.
-This is usually called pointer grabbing. It goes without saying that the user
-must always retain a way to forcefully reassert control over the pointer
-without the cooperation of the application.
-
-The solution is the enhancement of the 'Input::Session' interface by a new RPC
-function that allows a client to request exclusive input. The nitpicker GUI
-server grants this request if the application owns the focus. In scenarios
-using the window manager (wm), the focus is always defined by the wm, which
-happens to intercept all input sessions of GUI applications. Hence, the wm is
-in the natural position of arbitrating the grabbing/ungrabbing of the pointer.
-For each GUI client, the wm records whether the client is interested in
-exclusive input but does not forward this request to nitpicker. Only if a GUI
-client receives the focus and has requested exclusive input, the wm enables
-exclusive input for this client at nitpicker when observing a mouse click on
-the application window. Whenever the user presses the global wm key (super),
-the wm forcefully releases the exclusive input at nitpicker until the user
-clicks into the client window the next time.
-
-Furthermore, an application may enable exclusive input transiently during a
-key sequence, e.g., when dragging the mouse while holding the mouse button.
-Transient exclusive input is revoked as soon as the last button/key is
-released. It thereby would in principle allow for GUI controls like knobs to
-lock the pointer position while the user adjusts the value by moving the mouse
-while the mouse button is held. So the pointer retains its original position
-at the knob.
-
-While operating in exclusive input mode, there is no useful notion of an
-absolute pointer position at the nitpicker GUI server. Hence, nitpicker hides
-GUI domains that use the pointer position as coordinate origin. Thereby, the
-mouse cursor automatically disappears while the pointer is grabbed.
-
-
-Current state and ongoing work
-==============================
-
-All the advances described above are in full effect in the recently released
-version 24.10 of [https://genode.org/download/sculpt - Sculpt OS]. All
-components hosted in Genode's main and world repositories have been updated
-accordingly, including Genode-specific components like the widget toolkit
-used by the administrative user interface of Sculpt OS, window decorators,
-over Qt5 and Qt6, to SDL and SDL2.
-
-[image multiple_monitors]
-
-Current work is underway to implement multi-monitor window management and to
-make multiple monitors seamlessly available to guest OSes hosted in VirtualBox.
-Furthermore, the Intel display driver is currently getting equipped with the
-ability to use vsync interrupts for driving the interaction with the GUI
-server, taking the final step to attain tearing-free motion.
-
-
-Device drivers and platforms
-############################
-
-Linux device-driver environment (DDE)
-=====================================
-
-With our
-[https://genode.org/documentation/release-notes/24.08#Linux_device-driver_environment__DDE_ - recent]
-update of the DDE Linux kernel to version 6.6 for PC platforms and as a
-prerequisite to support the MNT Pocket Reform, we have adapted all drivers for
-the i.MX5/6/7/8 platforms to Linux kernel version 6.6.47. The list of drivers
-includes Wifi, NIC, display, GPU, USB and SD-card.
-
-
-MNT Pocket Reform
-~~~~~~~~~~~~~~~~~
-
-The [https://shop.mntre.com/products/mnt-pocket-reform - MNT Pocket Reform] is
-a Mini Laptop by MNT aiming to be modular, upgradable, and repairable while
-being assembled completely using open-source hardware. Being modular implies
-that a range of CPU modules is available for the MNT Pocket. Some of these
-chips, like the Rockchip based modules, are not officially supported by
-Genode, yet. But there is a choice of an i.MX8MP based module available which
-fits nicely into Genode's i.MX infrastructure.
-
-Genode already supports the MNT Reform 2 i.MX8MQ based
-[https://genodians.org/skalk/2020-06-29-mnt-reform - laptop]. So an update from
-MQ to MP doesn't sound like a big issue because only one letter changed,
-right? It turns out that there are more changes to the platform than mere
-adjustments of I/O resources and interrupt numbers. Additionally, the MNT
-Reform team offers quite a large patch set for each supported Linux kernel
-version. Luckily there is
-[https://source.mnt.re/reform/reform-debian-packages/-/tree/main/linux/patches6.6?ref_type=heads - one]
-for our just updated Linux 6.6 kernel. With this patch set, we were able to
-produce a Linux source tree (imx_linux) that we now take as basis for driver
-development on Genode. Note that these Linux kernel sources are shared by all
-supported i.MX platforms. Of course, additional patch series were necessary to
-include device-tree sources from other vendor kernels, for instance from
-Compulab.
-
-With the development environment in place and after putting lots of effort in,
-we ultimately achieved initial Genode support for the MNT Pocket Reform with
-Genode 24.11.
-
-On the device-driver side of things, we did not have to port lots of new
-drivers but were able to extend drivers already available for the i.MX8MQ
-platform. In particular these drivers are for the wired network card, USB host
-controller, display, and SD card.
-
-For the wireless network device that is found on the i.MX8MP SoM in the MNT
-Pocket Reform, we needed to port a new driver. It has a Qualcomm QCA9377
-chipset and is attached via SDIO. Unfortunately the available _ath10k_ driver
-in the vanilla kernel does not work properly with such a device and therefore
-is also not used in the regular Linux kernel for the MNT Pocket Reform. A
-slightly adapted external QCACLD2 reference driver is used instead. So we
-followed suit by incorporating this particular driver in our _imx_linux_
-source tree as well.
-
-[image sculpt_mnt_pocket]
-  Sculpt OS running on the MNT Pocket Reform
-
-Being the initial enablement, there are still some limitations.
-For example, the display of the MNT Pocket is physically
-[https://mntre.com/documentation/pocket-reform-handbook.pdf - rotated] by 90
-degrees. So, we had to find a way to accommodate for that. Unfortunately,
-there seems to be no hardware support other than using the GPU to perform
-a fast rotation. With GPU support still missing on this system, we had to
-resort to perform the rotation in software on the CPU, which is obviously
-far from optimal.
-Those early inefficiencies notwithstanding, Sculpt OS has become able to run
-on the MNT Pocket Reform. We will provide a preview image that exercises the
-available features soon.
-
-
-Platform driver for i.MX 8M Plus
-================================
-
-While enabling support for the MNT Pocket Reform (Section [MNT Pocket Reform]),
-it was necessary to adjust the i.MX8MP specific platform driver, which was
-originally introduced in the previous
-[https://genode.org/documentation/release-notes/24.08#Improvements_for_NXP_s_i.MX_family - release 24.08]
-to drive the Compulab i.MX 8M Plus IOT Gateway.
-
-Some of the I/O pin configurations necessary to set up the SoC properly are
-statically compiled into this driver because they do not change at runtime.
-However, the pin configuration is specific to the actual board. Therefore, the
-i.MX8MP platform driver now needs to distinguish between different boards (IOT
-Gateway and MNT Pocket) by evaluating the 'platform_info' ROM provided by
-core.
-
-Moreover, while working on different drivers, we detected a few missing clocks
-that were added to the platform driver. It turned out that some clocks that we
-initially turned off to save energy, have to be enabled to ensure the
-liveliness of the ARM Trusted Firmware (ATF) and thereby the platform. Also,
-we had to adapt the communication in between ATF and our platform driver to
-control power-domains. The first version of the i.MX8MP platform driver shared
-the ATF power-domains protocol with the i.MX8MQ version. However, the
-power-domain enumerations of the different firmwares varies also and we
-adapted that.
-
-Finally, the watchdog hardware is now served by the platform driver in a
-recurrent way. Originally our driver used the watchdog only to implement reset
-functionality. But in case of the MNT Pocket Reform, the watchdog hardware is
-already armed by the bootloader. Therefore, it needs to get served in time, to
-prevent the system from rebooting. As a consequence, the platform driver is
-mandatory on this platform if it needs to run longer than a minute.
-
-
-Wifi management rework
-======================
-
-Our management interface in the wifi driver served us well over the years
-and concealed the underlying complexity of the wireless stack. At the same
-time it gained some complexity itself to satisfy a variety of use-cases.
-Thus, we took the past release cycle as opportunity to rework the management
-layer to reduce its complexity by streamlining the interaction between
-various parts, like the manager layer itself, 'wpa_supplicant' as well as
-the device driver in order to provide a sound foundation for future
-adaptions.
-Included is also an update of the 'wpa_supplicant' to version 2.11.
-
-The following segments detail the changes made to the configuration options as
-they were altered quite a bit to no longer mix different tasks (e.g. joining a
-network and scanning for hidden networks) while removing obsolete options.
-
-At the top-level '<wifi_config>' node, the following alterations were made:
-
-* The 'log_level' attribute was added and configures the supplicant's
-  verbosity. Valid values correspond to levels used by the supplicant
-  and are as follows: 'excessive', 'msgdump', 'debug', 'info', 'warning',
-  and 'error'. The default value is 'error' and configures the least
-  amount of verbosity. This option was introduced to ease the investigation
-  of connectivity issues.
-
-* The 'bgscan' attribute may be used to configure the way the
-  supplicant performs background-scanning to steer or rather optimize
-  roaming decision within the same network. The default value is set
-  to 'simple:30:-70:600'. The attribute is forwarded unmodified to the WPA
-  supplicant and thus provides the syntax supported by the supplicant
-  implementation. It can be disabled by specifying an empty value, e.g.
-  'bgscan=""'.
-
-* The 'connected_scan_interval' attribute was removed as this functionality
-  is now covered by background scanning.
-
-* The 'verbose_state' attribute was removed altogether and similar
-  functionality is now covered by the 'verbose' attribute.
-
-The network management received the following changes:
-
-* Every configured network, denoted by a '<network>' node, is now implicitly
-  considered an option for joining. The 'auto_connect' attribute was
-  removed and a '<network>' node must be renamed or removed to deactivate
-  automatic connection establishment.
-
-* The intent to scan for a hidden network is now managed by the newly
-  introduced '<explicit_scan>' node that like the '<network>' node has
-  an 'ssid' attribute. If the specified SSID is valid, it is incorporated
-  into the scan request to actively probe for this network. As the node
-  requests explicit scanning only, a corresponding '<network>' node is
-  required to actually connect to the hidden network.
-  The 'explicit_scan' attribute of the '<network>' node has been removed.
-
-The following exemplary configuration shows how to configure the driver
-for attempting to join two different networks where one of them is hidden.
-The initial scan interval is set 10 seconds and the signal quality will be
-updated every 30 seconds while connected to a network.
-
-!<wifi_config scan_interval="10" update_quality_interval="30">
-!  <explicit_scan ssid="Skynet"/>
-!  <network ssid="Zero"   protection="WPA2" passphrase="allyourbase"/>
-!  <network ssid="Skynet" protection="WPA3" passphrase="illbeback"/>
-!</wifi_config>
-
-For more information please consult the driver's
-[https://github.com/genodelabs/genode/blob/master/repos/dde_linux/src/driver/wifi/README - documentation]
-that now features a best-practices section explaining how the driver should be
-operated at best, and highlights the difference between a managed (as used in
-Sculpt OS) and a user-generated configuration.
-
-
-Audio driver updated to OpenBSD 7.6
-===================================
-
-With this release, we updated our OpenBSD-based audio driver to a more recent
-revision that correlates to version 7.6. It supports newer devices, e.g. Alder
-Lake-N, and includes a fix for using message-signaled interrupts (MSI) with
-HDA devices as found in AMD-based systems.
-
-
-AVX and hardware-based AES in virtual machines
-==============================================
-
-The current release adds support for requesting and transferring the AVX FPU
-state via Genode's VM-session interface. With this prerequisite fulfilled, we
-enabled the announcement of the AVX feature to guest VMs in our port of
-VirtualBox6.
-
-Additionally, we enabled the announcement of AES and RDRAND CPU features to
-guest VMs to further improve the utilization of the hardware.
-
-
-Build system and tools
-######################
-
-Extended depot-tool safeguards
-------------------------------
-
-When using the run tool's '--depot-auto-update' feature while switching
-between different git topic branches with committed recipe hashes, a binary
-archive present in the depot may accidentally not match its ingredients
-because the depot/build tool's 'REBUILD=' mode - as used by the depot
-auto-update mechanism - merely looks at the archive versions. This situation
-is arguably rare. But when it occurs, its reach and effects are hard to
-predict. To rule out this corner case early, the depot/build tool has now been
-extended by recording the hashes of the ingredients of binary archives. When
-skipping a rebuild because the desired version presumably already exists as a
-binary archive, the recorded hashes are compared to the current state of the
-ingredients (src and api archives). Thereby inconsistencies are promptly
-reported to the user.
-
-Users of the depot tool will notice .hash files appearing alongside src and
-api archives. Those files contain the hash value of the content of the
-respective archive. Each binary archive built is now also accompanied by
-a .hash file, which contains a list of hash values of the ingredients that went
-into the binary archive. Thanks to these .hash files, the consistency between
-binaries and their ingredients can be checked quickly.
-
-_As a note of caution, when switching to the Genode 24.11 with existing depot,_
-_one will possibly need to remove existing depot archives (as listed by the_
-_diagnostic messages) because the existing archives are not accompanied by_
-_.hash files yet._

doc/road_map.txt

@@ -14,173 +14,128 @@ The road map is not fixed. If there is commercial interest of pushing the
 Genode technology to a certain direction, we are willing to revisit our plans.
 
 
-Review of 2023
+Review of 2021
 ##############
 
-The overarching theme of the road map in 2023 was the conquering of advanced
-platform aspects beyond mere functionality, speaking of temperature sensing,
-frequency control, battery monitoring, power management, and suspend/resume.
-We aimed at "Rocking the platforms we support!".
-The achievements made are best illustrated by the example of the Gen12
-Framework laptop. At the beginning of 2023, Sculpt OS was in principle working
-on this hardware, but with compromises that spoiled the user experience: fan
-noise, an erratic touchpad (using the firmware's PS/2 emulation), Fn key
-having no effect, strange issues when re-plugging an external display, and no
-indication of the battery state. By the end of 2023, not only were all these
-[https://genodians.org/nfeske/2023-11-03-sculpt-os#Framework_laptop - rough edges gone]
-but we even gained the ability to exercise
-[https://genode.org/documentation/release-notes/23.11#PC_power__frequency__temperature_sensing_and_control - precise control]
-over the machine's performance/frequency/temperature/power characteristics
-using an interactive GUI. It is fair to say that Genode advanced beyond the
-state of "working" and has entered the territory of "rocking". That said, not
-all lines of platform work such as suspend/resume are wrapped up yet.
+Genode's year 2021 was defined by three extremely challenging lines of work.
 
-Besides PC hardware, we put much emphasis on the PinePhone as a reference device
-for Genode on the phone. As one highlight of 2023, we got the
-[https://genodians.org/nfeske/2023-05-11-sculpt-os#Mobile_Sculpt_OS_on_the_PinePhone - mobile version of Sculpt OS]
-into the hands of a pilot group of users who provided instructive
-feedback to us. The system-update mechanism that Sculpt OS gained in April has
-been a game changer for such scenarios as it reduces the effort and risk of
-test-driving experimental versions to almost zero.
+First, we conquered the territory of GPU support that was ridden with
+uncertainties and seemed almost impenetrable when we started. But at the end
+of the year, our custom Intel-GPU multiplexer has landed in Sculpt OS like it
+always belonged there. In tandem with the Intel-GPU work, we explored the
+Vivante GPU as a representative of an ARM platform. The work required a deep
+dive into the respective GPU architectures and the Mesa software stack. It
+eventually led us to the design of Genode's device-agnostic GPU interfaces.
 
-At the beginning of 2023, we declared our ambition to run Sculpt OS on
-Genode's custom (base-hw) microkernel as alternative to the time-tested NOVA
-kernel. At that time, two showstoppers remained, namely
-[https://genode.org/documentation/release-notes/23.11#Kernel-agnostic_DMA_protection - DMA protection] and
-[https://genode.org/documentation/release-notes/23.11#Modernized_virtualization_interface - virtualization]
-support. Both of these deeply technical topics got covered over
-the course of the year. Refinements, optimizations, and real-world testing
-notwithstanding, we are happy to be well on track towards our goal.
+The second line of work was concerned with the reuse of Linux drivers as
+Genode components. Over the year, the puzzle pieces of our new Linux
+device-driver environment come together, replacing former confusion and chaos
+with knowledge and order, ultimately uncovering the treasure of Linux drivers
+for Genode with very little friction. On the way, we created new methodology
+and tooling, as well as extensive documentation in the form of the "Genode
+Platforms" document. Thanks to the new drivers ported from the Linux kernel,
+we were able to witness interactive Genode scenarios becoming alive on the
+PinePhone by the end of the year.
 
-Besides working on Genode's actual operating-system code, we fully embraced
-developer tooling as focus area. In 2023, the
-[https://genode.org/documentation/release-notes/23.08#Goa_tool_gets_usability_improvements_and_depot-index_publishing_support - Goa SDK]
-for streamlining the application development for Genode has reached the level
-of maturity and flexibility that allowed us to port software stacks as
-sophisticated as
-[https://genodians.org/jws/2023-11-16-sip-client-for-genode - Linphone]
-to Genode. Not only for porting but also for developing applications
-and libraries, the tool has become a go-to solution. As another noteworthy
-developer-tooling topic, we tirelessly followed our vision of on-target
-debugging on Sculpt OS. Specifically, we pursued the idea to implement a
-debugging instrument as a specialized version of init augmented with the GDB
-protocol. Sculpt OS 23.10 has this
-[https://genode.org/documentation/release-notes/23.08#Multi-component_debug_monitor - monitor component]
-already built-in, albeit it is not utilized yet.
+The third major topic was the growing sophistication of Genode-native
+workloads, with the media features of the Chromium-based browser on 64-bit ARM
+being the most impressive example. Apart from the apparent functional benefits
+for Genode and Sculpt OS, this is the long outstanding validation of some bold
+design decisions we took years ago, in particular the role and architecture of
+the VFS and its interplay with the libc.
+
+When reviewing the road map for 2021, some items remained uncovered. In
+particular the seL4-related topics became stale. At the end of 2020 - when we
+assembled the road map for the past year - there was a tangible prospect of
+pursuing this topic as funded work. However, those plans were repeatedly
+deferred and remained uncertain. Also, there are some items that have seen
+healthy doses of progress - like the topics related to Ada/SPARK or Goa - but
+received less attention than anticipated. On the other hand, the four releases
+([https://genode.org/documentation/release-notes/21.02 - 21.02],
+[https://genode.org/documentation/release-notes/21.05 - 21.05],
+[https://genode.org/documentation/release-notes/21.08 - 21.08],
+[https://genode.org/documentation/release-notes/21.11 - 21.11])
+of 2021 covered quite a few topics not advertised at the road
+map, e.g., webcam support, Xilinx Zynq, or RISC-V.
+
+It is fair to say that the level of technical risks we took in 2021 had been
+unprecedented in Genode's development history. We are more than proud of the
+outcome, which will hopefully propel Genode to new heights in 2022.
 
 
-2024 - Sculpt OS usability
-##########################
+2022 - Mobile Usability
+#######################
 
-During our annual road-map discussion on Genode's
-[https://genode.org/community/mailing-lists - mailing list], it became
-apparent that many of us developers long for harvesting user-visible rewards
-after concentrating so intensively on topics below the surface,
-eagerly rallying behind the theme "Sculpt OS usability" for 2024.
+After having enabled the first interactive Genode scenarios on the PinePhone
+last year, we plan to take Genode on the PinePhone to a level where we can
+routinely use it for advanced applications, in particular video chat. This
+vision confronts us with a multitude of hard technical nuts to crack such as
+power efficiency, UI latency, quality-of-service of audio processing, drivers
+for multi-media devices, WebRTC performance, and usability. This grand theme
+will not only address the PinePhone specifically. The efficiency gains will
+benefit all Genode use cases large and small.
 
-Of the many aspects of usability, the following stood out during the
-discussion: multi-monitor support, desktop utilities (file management,
-configuration dialogs, drag'n'drop), improved discoverability (on-target docs),
-suspend/resume, and profound support for touchscreens and touchpads.
-Accommodating those topics will require us to rethink several parts of the GUI
-stack, from the drivers over the low-level GUI server, window management, up
-to the application and widget-toolkit level.
+Our theme of the Genode-based video chat on the PinePhone fuels several
+ambitions in closely related areas. In particular, we aspire using WireGuard
+to secure private communication, and experiment with the operation of
+hardware-based trust anchors as the basis for encrypted storage and
+communication.
 
-A second recurring interest is the further consolidation of Genode's driver
-landscape towards fully pluggable drivers, the consistent use of drivers
-ported from up-to-date Linux kernels, and clear-cut ACPI support.
-
-As continuations of 2023, the vision of Sculpt OS on Genode's custom kernel
-will come to fruition, and we will bring our goal of easy-to-use on-target
-debugging to completion.
-
-Since we added
-[https://genodians.org/atopia/2023-10-26-a-first-complex-rust-package - Rust support]
-to the Goa tool mid of 2023, we have been looking for natural synergies
-between Rust-based projects and Genode. During the road-map discussion, we
-identified the use of Rust-based components as building blocks for a
-multi-component e-mail client a tempting opportunity. Throughout the year, we
-plan to take an (open-ended) e-mail scenario as motivator for combining our
-interests in Sculpt usability, Goa-based development work flows, and Rust.
-
-Device-wise, we will continue our engagement with the PinePhone, look forward
-to the upcoming MNT PocketReform, and take on the latest Intel-based PC
-platforms. We also want to explore the use of Sculpt OS on form factors like
-the ZimaBlade single-board server (headless operation) or the StarLite tablet
-(touch-based UI).
+Besides the PinePhone, we will steadily nurture the quality and scope of
+driver support on PC hardware, which remains the primary platform for the
+day-to-day use of Sculpt OS. So you can expect us to keep up with recent
+generations of Intel-based hardware. In this area, we plan to make IOMMU
+support available with kernels beyond NOVA, and explore the use of
+power-management features like suspend-resume with Sculpt OS.
 
 
-Milestones for 2024
+Milestones for 2022
 ###################
 
-February - Release 24.02
+In the following, we present a rough schedule of the planned work. As usual,
+it is not set in stone. If you are interested in a particular line of work,
+please get in touch.
+
+
+February - Release 22.02
 ========================
 
-* Revised audio infrastructure
-  (timing robustness, pluggable drivers, adaptive sample rates)
-* Suspend/resume awareness of GPU, AHCI, and NVMe drivers
-* Support for I2C based HID devices in Intel GEN12 (e.g., touchpad)
-* Fine-grained and dynamic assignment of USB devices/interfaces
-* Use of Sculpt OS as a remote test target for Goa
-* TCP/IP stack based of DDE-Linux version 6.x
-* PinePhone support for receiving and sending SMS messages
+* OpenGL in VirtualBox 6
+* Sculpt OS as tool kit for special-purpose OS images
+* PinePhone
+  * Modem access
+  * Touch-screen compatibility of Sculpt OS
 
 
-May - Release 24.05
+May - Release 22.05
 ===================
 
-* Sculpt OS on the PC
-  * Suspend/resume
-  * Scalability to large monitors
-  * On-target debugging
-  * Scrollable component graph
-  * Controls for saving the current deployment and settings
-* Updated "Genode Foundations" book
-* Drivers
-  * Revised PC platform discovery and ACPI sandboxing
-  * i.MX drivers updated to DDE-Linux version 6.x
-  * ALSA-based audio driver for PC platforms
-  * Audio on MNT Reform
-  * Alder Lake GPU support + updated Mesa library stack
-* Audio components converted to new APIs introduced in 24.02
-* Optimized base-hw multimedia support
-  (kernel scheduling, latency, cache attributes)
-* First Sculpt PC variant on the base-hw kernel
-  (integration of the kernel-agnostic IOMMU support, virtualization)
-* Consolidation of the Tresor block encryptor and file vault
-* Application-level compositing using Genode's dialog API
+* Annual update of the "Genode Foundations" book
+* Second edition of the "Genode Platforms" documentation
+* WireGuard VPN
+* Updated drivers for PC hardware (Wifi, Intel framebuffer, USB)
+* New tracing tool with support for CTF and PCAP
+* PinePhone telephony
 
 
-August - Release 24.08
+August - Release 22.08
 ======================
 
-* Sculpt OS
-  * Low-complexity custom file manager
-  * User profiles
-  * On-target documentation view
-  * Assignment of individual directories as file systems
-* DDE-Linux update to kernel version 6.6 LTS
-* Updating Qt and QtWebEngine to Qt6
-* GUI stack
-  * Multi-monitor support
-  * Tearing-free graphics
-  * Touch aware GUI server and window manager
-  * Drag'n'drop between applications
-  * Mouse grabbing
-* Convenience UI tools showcasing the use of the Goa SDK
-  (e.g., NIC-router config, USB-passthrough config, file launcher)
-* User-friendly bootstrapping/installation of Linux VMs on ARM
+* PinePhone
+  * Morph browser
+  * Media record and playback capabilities
+* FPGA-powered DMA protection for the Zynq-7000 SoC
+* Kernel-agnostic IOMMU support for PC hardware
+* Optimized GUI latency and synchronization
 
 
-November - Release 24.11
+November - Release 22.11
 ========================
 
-* Sculpt OS
-  * Multi-monitor window management
-  * Use of dev tools on target
-* "Genode applications" book focused on component development
-* Port of Qemu via Goa
-* Dynamic VFS configuration, VFS / file-system interface optimizations
-* Pluggable USB-Host driver
-* Show case of a multi-component e-mail user agent
+* PinePhone
+  * WebRTC-based video chat
+  * Power management
+* Base mechanism for suspend-resume on PC hardware
+* Support for hardware-based trust anchor for CBE and WireGuard
+* Software-hardware co-design example for the Zynq-7000 SoC
 

doc/tool_chain.txt

@@ -30,18 +30,16 @@ tool chain. It can be obtained in two ways: as pre-compiled binaries or
 manually compiled:
 
 :Pre-compiled:
-  [https://github.com/genodelabs/genode/releases/download/23.05/genode-toolchain-23.05.tar.xz - Download the tool chain]
-  pre-compiled for Linux x86_64.
-
-  ! SHA256 880886efba0f592a3d3c5ffb9fa63e692cb6bd643e13c5c468d0da027c22716e
-
+  Our pre-compiled tool chain is runnable on Linux x86_32 and x86_64. The
+  archives for both versions will be extracted to
+  _/usr/local/genode/tool/<version>_.
   To extract the archive, use the following command:
-
   ! sudo tar xPf genode-toolchain-<version>-<arch>.tar.xz
-
   The use of the 'P' option ensures that the tool chain will be installed at
-  _/usr/local/genode/tool/<version>_, which is the location expected by
-  Genode's build system.
+  the correct absolute path where the build system expects it to reside by
+  default. Please note, Genode OS Framework releases require a Genode tool
+  chain with an equal or next smaller version number.
+  [https://sourceforge.net/projects/genode/files/genode-toolchain/ - Download the pre-compiled tool chain...]
 
 :Compile from source:
   For those of you who prefer compiling the tool chain from source, we provide

repos/base-fiasco/lib/mk/base-fiasco.mk

@@ -4,6 +4,6 @@ LIBS += syscall-fiasco base-fiasco-common cxx timeout
 
 SRC_CC += thread_start.cc
 SRC_CC += cache.cc
-SRC_CC += capability_slab.cc
 SRC_CC += capability_space.cc
 SRC_CC += signal_transmitter.cc signal.cc
+SRC_CC += platform.cc

repos/base-fiasco/lib/mk/kernel-fiasco.inc

@@ -1,4 +1,4 @@
-L4_SRC_DIR := $(call select_from_ports,fiasco)/src/kernel/fiasco/fiasco/snapshot
+L4_SRC_DIR = $(call select_from_ports,fiasco)/src/kernel/fiasco/fiasco/snapshot
 
 FIASCO_BUILD_DIR = $(shell pwd)/build
 FIASCO           = $(FIASCO_BUILD_DIR)/fiasco
@@ -6,15 +6,8 @@ FIASCO_SRC       = $(L4_SRC_DIR)/kernel/fiasco
 
 KERNEL_BUILD_OUTPUT_FILTER = 2>&1 | sed "s/^/      [fiasco]  /"
 
-KERNEL_CFLAGS = -std=gnu89 \
-                -fno-tree-loop-distribute-patterns \
-                $(CWARN)
-
-KERNEL_CXXFLAGS = -std=gnu++98 \
-                  -fno-delete-null-pointer-checks \
-                  -fno-tree-loop-distribute-patterns \
-                  -Wno-address-of-packed-member \
-                  $(CXXWARN)
+KERNEL_CXXFLAGS = -std=gnu++98 -fno-delete-null-pointer-checks $(CXXWARN) \
+                  -Wno-address-of-packed-member
 
 $(FIASCO_BUILD_DIR):
 	$(VERBOSE_MK) MAKEFLAGS= $(MAKE) SYSTEM_TARGET="$(CROSS_DEV_PREFIX)" \
@@ -27,8 +20,7 @@ $(FIASCO_BUILD_DIR):
 	$(VERBOSE)cp $(KERNEL_CONFIG) $@/globalconfig.out
 
 $(FIASCO): $(FIASCO_BUILD_DIR)
-	$(VERBOSE_MK) MAKEFLAGS= \
-	              CFLAGS="$(KERNEL_CFLAGS)" \
+	$(VERBOSE_MK) MAKEFLAGS= CFLAGS="-std=gnu89 $(CWARN)" \
 	              CXXFLAGS="$(KERNEL_CXXFLAGS)" \
 	              $(MAKE) SYSTEM_TARGET="$(CROSS_DEV_PREFIX)" \
 	                                 $(VERBOSE_DIR) -C $(FIASCO_BUILD_DIR) \

repos/base-fiasco/lib/mk/l4_pkg.inc

@@ -65,10 +65,8 @@ CXXWARN = $(WARN) -Wno-bool-compare -Wno-c++11-compat -Wno-class-memaccess
 #
 %.tag:
 	$(VERBOSE_MK) MAKEFLAGS= CPPFLAGS="$(CC_MARCH)" \
-	              CFLAGS="$(CC_MARCH) -std=gnu89 $(CWARN) \
-	                      -fno-tree-loop-distribute-patterns" \
-	              CXXFLAGS="$(CC_MARCH) -D_GNU_SOURCE -std=gnu++98 $(CXXWARN) \
-	                        -fno-tree-loop-distribute-patterns" \
+	              CFLAGS="$(CC_MARCH) -std=gnu89 $(CWARN)" \
+	              CXXFLAGS="$(CC_MARCH) -D_GNU_SOURCE -std=gnu++98 $(CXXWARN)" \
 	              ASFLAGS="$(CC_MARCH)" LDFLAGS="$(LD_MARCH)" \
 	              $(MAKE) $(VERBOSE_DIR) O=$(L4_BUILD_DIR) $(L4_VERBOSE) \
 	                      -C $(L4_PKG_DIR)/$* \

repos/base-fiasco/lib/mk/syscall-fiasco.inc

@@ -6,7 +6,7 @@
 # userland that comes with Fiasco.
 #
 
-L4_SRC_DIR   := $(call select_from_ports,fiasco)/src/kernel/fiasco/fiasco/snapshot
+L4_SRC_DIR    = $(call select_from_ports,fiasco)/src/kernel/fiasco/fiasco/snapshot
 L4_BUILD_DIR := $(shell pwd)
 
 #

repos/base-fiasco/patches/gcc12.patch

@@ -1,15 +0,0 @@
-gcc12.patch
-
-diff --git fiasco/snapshot/l4/pkg/sigma0/server/src/region.h fiasco/snapshot/l4/pkg/sigma0/server/src/region.h
-index ad7cf95..c323bae 100644
---- fiasco/snapshot/l4/pkg/sigma0/server/src/region.h
-+++ fiasco/snapshot/l4/pkg/sigma0/server/src/region.h
-@@ -1,6 +1,8 @@
- #ifndef SIGMA0_REGION_H__
- #define SIGMA0_REGION_H__
- 
-+#include <l4/cxx/iostream.h>
-+
- class Region
- {
- private:

repos/base-fiasco/ports/fiasco.hash

@@ -1 +1 @@
-8b9803659db40a251898289ef8f347351aeaf29d
+386db79cbd4039ea2e3cbf028fac095a1bc96c31

repos/base-fiasco/ports/fiasco.port

@@ -1,10 +1,10 @@
 LICENSE     := GPLv2
 VERSION     := 1.0
 DOWNLOADS   := fiasco.archive
-URL(fiasco) := https://genode.org/files/fiasco.tar.bz2
+URL(fiasco) := http://downloads.sourceforge.net/project/genode/3rd/3rd_fiasco.tar.bz2
 SHA(fiasco) := b5737901001e6ab09adecf03914c0a7e04f03a2d561e9b2c7a12f3c92edc7dd0
 DIR(fiasco) := src/kernel/fiasco
-PATCHES     := $(sort $(wildcard $(REP_DIR)/patches/*.patch))
+PATCHES     := $(shell find $(REP_DIR)/patches -name *.patch)
 PATCH_OPT   := -p0 -d src/kernel/fiasco
 
 $(call check_tool,wget)

repos/base-fiasco/recipes/src/base-fiasco/content.mk

@@ -21,5 +21,5 @@ content:
 	for spec in x86_32; do \
 	  mv lib/mk/spec/$$spec/ld-fiasco.mk lib/mk/spec/$$spec/ld.mk; \
 	  done;
-	sed -i "s/fiasco_timer/timer/" src/timer/fiasco/target.mk
+	sed -i "s/fiasco_timer_drv/timer/" src/timer/fiasco/target.mk
 

repos/base-fiasco/recipes/src/base-fiasco/hash

@@ -1 +1 @@
-2024-12-10 408b474f632eefaaa19db35812a9aa94a48e6bdb
+2022-10-11 1f0607de6493bad0e47b24e66d84474652e8b6be

repos/base-fiasco/src/core/core_log_out.cc

@@ -17,7 +17,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Core_log::out(char const c) { Fiasco::outchar(c); }

repos/base-fiasco/src/core/include/ipc_pager.h

@@ -30,10 +30,10 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-namespace Core { class Ipc_pager; }
+namespace Genode { class Ipc_pager; }
 
 
-class Core::Ipc_pager
+class Genode::Ipc_pager
 {
 	private:
 

repos/base-fiasco/src/core/include/map_local.h

@@ -21,7 +21,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-namespace Core {
+namespace Genode {
 
 	/**
 	 * Map page locally within core

repos/base-fiasco/src/core/include/platform.h

@@ -29,10 +29,10 @@
 #include <boot_modules.h>
 #include <assertion.h>
 
-namespace Core { class Platform; }
+namespace Genode { class Platform; }
 
 
-class Core::Platform : public Platform_generic
+class Genode::Platform : public Platform_generic
 {
 	private:
 
@@ -45,7 +45,7 @@ class Core::Platform : public Platform_generic
 		/*
 		 * Shortcut for the type of allocator instances for physical resources
 		 */
-		using Phys_allocator = Synced_range_allocator<Allocator_avl>;
+		typedef Synced_range_allocator<Allocator_avl> Phys_allocator;
 
 		char           _core_label[1];      /* to satisfy _core_pd */
 		Platform_pd   *_core_pd = nullptr;  /* core protection domain object */
@@ -112,8 +112,7 @@ class Core::Platform : public Platform_generic
 			 */
 			Sigma0();
 
-			/* never called */
-			Pager_result pager(Ipc_pager &) override { return Pager_result::STOP; }
+			int pager(Ipc_pager &) override { /* never called */ return -1; }
 		};
 
 		/**
@@ -131,8 +130,7 @@ class Core::Platform : public Platform_generic
 			 */
 			Core_pager(Platform_pd &core_pd);
 
-			/* never called */
-			Pager_result pager(Ipc_pager &) override { return Pager_result::STOP; }
+			int pager(Ipc_pager &) override { /* never called */ return -1; }
 		};
 
 		/**

repos/base-fiasco/src/core/include/platform_pd.h

@@ -21,27 +21,21 @@
 #include <base/allocator.h>
 
 /* core includes */
+#include <platform_thread.h>
 #include <address_space.h>
 
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-namespace Core {
+namespace Genode {
 
 	class Platform_thread;
 	class Platform_pd;
 }
 
 
-class Core::Platform_pd : public Address_space
+class Genode::Platform_pd : public Address_space
 {
-	public:
-
-		struct Thread_id { unsigned value; };
-
-		enum class Alloc_thread_id_error { EXHAUSTED };
-		using Alloc_thread_id_result = Attempt<Thread_id, Alloc_thread_id_error>;
-
 	private:
 
 		/*
@@ -66,11 +60,35 @@ class Core::Platform_pd : public Address_space
 		Fiasco::l4_taskid_t _l4_task_id { };  /* L4 task ID */
 
 
-		/***************************************
-		 ** Threads of this protection domain **
-		 ***************************************/
+		/**********************************************
+		 ** Threads of this protection domain object **
+		 **********************************************/
 
-		Platform_thread *_threads[THREAD_MAX] { };
+		Platform_thread *_threads[THREAD_MAX];
+
+		/**
+		 * Initialize thread allocator
+		 */
+		void _init_threads();
+
+		/**
+		 * Thread iteration for one task
+		 */
+		Platform_thread *_next_thread();
+
+		/**
+		 * Thread allocation
+		 *
+		 * Again a special case for Core thread0.
+		 */
+		int _alloc_thread(int thread_id, Platform_thread &thread);
+
+		/**
+		 * Thread deallocation
+		 *
+		 * No special case for Core thread0 here - we just never call it.
+		 */
+		void _free_thread(int thread_id);
 
 
 		/******************
@@ -161,25 +179,18 @@ class Core::Platform_pd : public Address_space
 		static void init();
 
 		/**
-		 * Allocate PD-local ID for a new 'Platform_thread'
+		 * Bind thread to protection domain
+		 *
+		 * \return true on success
 		 */
-		Alloc_thread_id_result alloc_thread_id(Platform_thread &);
+		bool bind_thread(Platform_thread &thread);
 
 		/**
-		 * Release PD-local thread ID at destruction of 'Platform_thread'
+		 * Unbind thread from protection domain
+		 *
+		 * Free the thread's slot and update thread object.
 		 */
-		void free_thread_id(Thread_id);
-
-		/**
-		 * Return L4 thread ID from the PD's task ID and the PD-local thread ID
-		 */
-		Fiasco::l4_threadid_t l4_thread_id(Thread_id const id) const
-		{
-			Fiasco::l4_threadid_t result = _l4_task_id;
-			enum { LTHREAD_MASK = (1 << 7) - 1 };
-			result.id.lthread = id.value & LTHREAD_MASK;
-			return result;
-		}
+		void unbind_thread(Platform_thread &thread);
 
 		/**
 		 * Assign parent interface to protection domain

repos/base-fiasco/src/core/include/platform_thread.h

@@ -27,14 +27,14 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-namespace Core {
+namespace Genode {
 
 	class Platform_pd;
 	class Platform_thread;
 }
 
 
-class Core::Platform_thread : Interface
+class Genode::Platform_thread : Interface
 {
 	private:
 
@@ -44,74 +44,92 @@ class Core::Platform_thread : Interface
 		Platform_thread(Platform_thread const &);
 		Platform_thread &operator = (Platform_thread const &);
 
-		using Name = String<32>;
+		int _thread_id = THREAD_INVALID;       /* plain thread number */
 
-		Name const _name; /* name to be registered at the kernel debugger */
-
-		Platform_pd &_pd;
-
-		using Id = Platform_pd::Alloc_thread_id_result;
-
-		Id const _id { _pd.alloc_thread_id(*this) };
+		Fiasco::l4_threadid_t _l4_thread_id;
 
+		typedef String<32> Name;
+		Name const _name;                      /* thread name that will be
+		                                          registered at the kernel
+		                                          debugger */
+		Platform_pd *_platform_pd = nullptr;   /* protection domain thread
+		                                          is bound to */
 		Pager_object *_pager = nullptr;
 
 	public:
 
+		enum {
+			THREAD_INVALID = -1,  /* invalid thread number */
+		};
+
 		/**
 		 * Constructor
 		 */
-		Platform_thread(Platform_pd &pd, Rpc_entrypoint &, Ram_allocator &,
-		                Region_map &, size_t, const char *name, unsigned,
-		                Affinity::Location, addr_t)
-		: _name(name), _pd(pd) { }
+		Platform_thread(size_t, const char *name, unsigned priority,
+		                Affinity::Location, addr_t utcb);
 
 		/**
 		 * Constructor used for core-internal threads
 		 */
-		Platform_thread(Platform_pd &pd, const char *name)
-		: _name(name), _pd(pd) { }
+		Platform_thread(const char *name);
 
 		/**
 		 * Destructor
 		 */
 		~Platform_thread();
 
-		/**
-		 * Return false if thread IDs are exhausted
-		 */
-		bool valid() const { return _id.ok(); }
-
 		/**
 		 * Start thread
 		 *
 		 * \param ip  instruction pointer to start at
 		 * \param sp  stack pointer to use
+		 *
+		 * \retval  0  successful
+		 * \retval -1  thread could not be started
 		 */
-		void start(void *ip, void *sp);
+		int start(void *ip, void *sp);
 
 		/**
 		 * Pause this thread
 		 */
-		void pause() { /* not implemented */ }
+		void pause();
 
 		/**
 		 * Enable/disable single stepping
 		 */
-		void single_step(bool) { /* not implemented */ }
+		void single_step(bool) { }
 
 		/**
 		 * Resume this thread
 		 */
-		void resume() { /* not implemented */ }
+		void resume();
+
+		/**
+		 * This thread is about to be bound
+		 *
+		 * \param thread_id     local thread ID
+		 * \param l4_thread_id  final L4 thread ID
+		 * \param pd            platform pd, thread is bound to
+		 */
+		void bind(int thread_id, Fiasco::l4_threadid_t l4_thread_id,
+		          Platform_pd &pd);
+
+		/**
+		 * Unbind this thread
+		 */
+		void unbind();
 
 		/**
 		 * Override thread state with 's'
+		 *
+		 * \throw Cpu_session::State_access_failed
 		 */
-		void state(Thread_state) { /* not implemented */ }
+		void state(Thread_state s);
 
 		/**
 		 * Read thread state
+		 *
+		 * \throw Cpu_session::State_access_failed
 		 */
 		Thread_state state();
 
@@ -149,7 +167,7 @@ class Core::Platform_thread : Interface
 		 * Return identification of thread when faulting
 		 */
 		unsigned long pager_object_badge() const {
-			return convert_native_thread_id_to_badge(native_thread_id()); }
+			return convert_native_thread_id_to_badge(_l4_thread_id); }
 
 		/**
 		 * Set CPU quota of the thread to 'quota'
@@ -166,16 +184,9 @@ class Core::Platform_thread : Interface
 		 ** Fiasco-specific Accessors **
 		 *******************************/
 
-		Fiasco::l4_threadid_t native_thread_id() const
-		{
-			using namespace Fiasco;
-			return _id.convert<l4_threadid_t>(
-				[&] (Platform_pd::Thread_id id) { return _pd.l4_thread_id(id); },
-				[&] (Platform_pd::Alloc_thread_id_error) { return L4_INVALID_ID; }
-			);
-		}
-
-		Name name() const { return _name; }
+		int                   thread_id()        const { return _thread_id; }
+		Fiasco::l4_threadid_t native_thread_id() const { return _l4_thread_id; }
+		Name                  name()             const { return _name; }
 };
 
 #endif /* _CORE__INCLUDE__PLATFORM_THREAD_H_ */

repos/base-fiasco/src/core/include/rpc_cap_factory.h

@@ -18,13 +18,10 @@
 #include <base/allocator.h>
 #include <base/capability.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core { class Rpc_cap_factory; }
+namespace Genode { class Rpc_cap_factory; }
 
 
-class Core::Rpc_cap_factory
+class Genode::Rpc_cap_factory
 {
 	private:
 

repos/base-fiasco/src/core/include/util.h

@@ -28,10 +28,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core {
+namespace Genode {
 
 	inline void log_event(const char *s)
 	{
@@ -98,7 +95,7 @@ namespace Core {
 	inline addr_t map_src_addr(addr_t core_local_addr, addr_t) {
 		return core_local_addr; }
 
-	inline Log2 kernel_constrained_map_size(Log2 size) { return size; }
+	inline size_t constrain_map_size_log2(size_t size_log2) { return size_log2; }
 
 	inline unsigned long convert_native_thread_id_to_badge(Fiasco::l4_threadid_t tid)
 	{

repos/base-fiasco/src/core/io_mem_session_support.cc

@@ -19,10 +19,10 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
-void Io_mem_session_component::_unmap_local(addr_t base, size_t, addr_t)
+void Io_mem_session_component::_unmap_local(addr_t base, size_t)
 {
 	platform().region_alloc().free(reinterpret_cast<void *>(base));
 }
@@ -38,11 +38,8 @@ static inline bool can_use_super_page(addr_t, size_t)
 }
 
 
-Io_mem_session_component::Map_local_result Io_mem_session_component::_map_local(addr_t const phys_base,
-                                                                                size_t const size_in)
+addr_t Io_mem_session_component::_map_local(addr_t phys_base, size_t size)
 {
-	size_t const size = size_in;
-
 	auto map_io_region = [] (addr_t phys_base, addr_t local_base, size_t size)
 	{
 		using namespace Fiasco;
@@ -94,16 +91,14 @@ Io_mem_session_component::Map_local_result Io_mem_session_component::_map_local(
 	size_t align = (size >= get_super_page_size()) ? get_super_page_size_log2()
 	                                               : get_page_size_log2();
 
-	return platform().region_alloc().alloc_aligned(size, align).convert<Map_local_result>(
+	return platform().region_alloc().alloc_aligned(size, align).convert<addr_t>(
 
 		[&] (void *ptr) {
 			addr_t const core_local_base = (addr_t)ptr;
 			map_io_region(phys_base, core_local_base, size);
-			return Map_local_result { .core_local_addr = core_local_base, .success = true };
-		},
+			return core_local_base; },
 
-		[&] (Range_allocator::Alloc_error) {
+		[&] (Range_allocator::Alloc_error) -> addr_t {
 			error("core-local mapping of memory-mapped I/O range failed");
-			return Map_local_result();
-		});
+			return 0; });
 }

repos/base-fiasco/src/core/irq_session_component.cc

@@ -12,17 +12,17 @@
  */
 
 /* Genode includes */
+#include <base/log.h>
 #include <util/arg_string.h>
 
 /* core includes */
 #include <irq_root.h>
-#include <irq_args.h>
 #include <util.h>
 
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 bool Irq_object::_associate()
@@ -78,11 +78,10 @@ void Irq_object::_wait_for_irq()
 }
 
 
-Thread::Start_result Irq_object::start()
+void Irq_object::start()
 {
-	Start_result const result = ::Thread::start();
+	::Thread::start();
 	_sync_bootup.block();
-	return result;
 }
 
 
@@ -127,9 +126,7 @@ Irq_session_component::Irq_session_component(Range_allocator &irq_alloc,
 	_irq_alloc(irq_alloc),
 	_irq_object(_irq_number)
 {
-	Irq_args irq_args(args);
-	bool msi { irq_args.type() != Irq_session::TYPE_LEGACY };
-
+	long msi = Arg_string::find_arg(args, "device_config_phys").long_value(0);
 	if (msi)
 		throw Service_denied();
 

repos/base-fiasco/src/core/pager.cc

@@ -11,6 +11,9 @@
  * under the terms of the GNU Affero General Public License version 3.
  */
 
+/* Genode includes */
+#include <base/log.h>
+
 /* core includes */
 #include <ipc_pager.h>
 #include <pager.h>
@@ -22,7 +25,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 using namespace Fiasco;
 
 
@@ -103,6 +106,3 @@ Untyped_capability Pager_entrypoint::_pager_object_cap(unsigned long badge)
 {
 	return Capability_space::import(native_thread().l4id, Rpc_obj_key(badge));
 }
-
-
-void Core::init_page_fault_handling(Rpc_entrypoint &) { }

repos/base-fiasco/src/core/pager_object.cc

@@ -20,7 +20,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Pager_object::wake_up()
@@ -45,5 +45,5 @@ void Pager_object::wake_up()
 
 void Pager_object::unresolved_page_fault_occurred()
 {
-	state.state = Thread_state::State::PAGE_FAULT;
+	state.unresolved_page_fault = true;
 }

repos/base-fiasco/src/core/platform.cc

@@ -12,6 +12,7 @@
  */
 
 /* Genode includes */
+#include <base/log.h>
 #include <base/allocator_avl.h>
 #include <base/sleep.h>
 #include <util/misc_math.h>
@@ -34,7 +35,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 using namespace Fiasco;
 
 
@@ -123,7 +124,7 @@ static void _core_pager_loop()
 }
 
 
-Core::Platform::Sigma0::Sigma0()
+Platform::Sigma0::Sigma0()
 :
 	Pager_object(Cpu_session_capability(), Thread_capability(),
 	             0, Affinity::Location(), Session_label(),
@@ -133,22 +134,23 @@ Core::Platform::Sigma0::Sigma0()
 }
 
 
-Core::Platform::Sigma0 &Core::Platform::sigma0()
+Platform::Sigma0 &Platform::sigma0()
 {
 	static Sigma0 _sigma0;
 	return _sigma0;
 }
 
 
-Core::Platform::Core_pager::Core_pager(Platform_pd &core_pd)
+Platform::Core_pager::Core_pager(Platform_pd &core_pd)
 :
-	Platform_thread(core_pd, "core.pager"),
+	Platform_thread("core.pager"),
 	Pager_object(Cpu_session_capability(), Thread_capability(),
 	             0, Affinity::Location(), Session_label(),
 	             Cpu_session::Name(name()))
 {
 	Platform_thread::pager(sigma0());
 
+	core_pd.bind_thread(*this);
 	cap(Capability_space::import(native_thread_id(), Rpc_obj_key()));
 
 	/* pager needs to know core's pd ID */
@@ -166,7 +168,7 @@ Core::Platform::Core_pager::Core_pager(Platform_pd &core_pd)
 }
 
 
-Core::Platform::Core_pager &Core::Platform::core_pager()
+Platform::Core_pager &Platform::core_pager()
 {
 	static Core_pager _core_pager(core_pd());
 	return _core_pager;
@@ -248,7 +250,7 @@ static inline int sigma0_req_region(addr_t *addr, unsigned log2size)
 }
 
 
-void Core::Platform::_setup_mem_alloc()
+void Platform::_setup_mem_alloc()
 {
 	/*
 	 * Completely map program image by touching all pages read-only to
@@ -295,7 +297,7 @@ void Core::Platform::_setup_mem_alloc()
 }
 
 
-void Core::Platform::_setup_irq_alloc()
+void Platform::_setup_irq_alloc()
 {
 	_irq_alloc.add_range(0, 0x10);
 }
@@ -346,10 +348,13 @@ static l4_kernel_info_t *get_kip()
 }
 
 
-void Core::Platform::_setup_basics()
+void Platform::_setup_basics()
 {
 	l4_kernel_info_t * kip = get_kip();
 
+	/* add KIP as ROM module */
+	_rom_fs.insert(&_kip_rom);
+
 	/* parse memory descriptors - look for virtual memory configuration */
 	/* XXX we support only one VM region (here and also inside RM) */
 	using L4::Kip::Mem_desc;
@@ -396,12 +401,12 @@ void Core::Platform::_setup_basics()
 }
 
 
-Core::Platform::Platform()
+Platform::Platform()
 :
 	_ram_alloc(nullptr), _io_mem_alloc(&core_mem_alloc()),
 	_io_port_alloc(&core_mem_alloc()), _irq_alloc(&core_mem_alloc()),
 	_region_alloc(&core_mem_alloc()),
-	_kip_rom(_rom_fs, "l4v2_kip", (addr_t)get_kip(), L4_PAGESIZE)
+	_kip_rom((addr_t)get_kip(), L4_PAGESIZE, "l4v2_kip")
 {
 	/*
 	 * We must be single-threaded at this stage and so this is safe.
@@ -431,9 +436,10 @@ Core::Platform::Platform()
 	 * interface that allows us to specify the lthread number.
 	 */
 	Platform_thread &core_thread = *new (core_mem_alloc())
-		Platform_thread(*_core_pd, "core.main");
+		Platform_thread("core.main");
 
 	core_thread.pager(sigma0());
+	_core_pd->bind_thread(core_thread);
 
 	/* we never call _core_thread.start(), so set name directly */
 	fiasco_register_thread_name(core_thread.native_thread_id(),
@@ -454,8 +460,8 @@ Core::Platform::Platform()
 				memset(core_local_ptr, 0, size);
 				content_fn(core_local_ptr, size);
 
-				new (core_mem_alloc())
-					Rom_module(_rom_fs, rom_name, phys_addr, size);
+				_rom_fs.insert(new (core_mem_alloc())
+				               Rom_module(phys_addr, size, rom_name));
 			},
 			[&] (Range_allocator::Alloc_error) {
 				warning("failed to export ", rom_name, " as ROM module"); }
@@ -472,8 +478,8 @@ Core::Platform::Platform()
 		[&] (void *core_local_ptr, size_t size) {
 			Xml_generator xml(reinterpret_cast<char *>(core_local_ptr),
 			                  size, "platform_info",
-				[&] {
-					xml.node("kernel", [&] {
+				[&] () {
+					xml.node("kernel", [&] () {
 						xml.attribute("name", "fiasco"); }); }); });
 }
 
@@ -482,7 +488,7 @@ Core::Platform::Platform()
  ** Generic platform interface **
  ********************************/
 
-void Core::Platform::wait_for_exit()
+void Platform::wait_for_exit()
 {
 	/*
 	 * On Fiasco, Core never exits. So let us sleep forever.

repos/base-fiasco/src/core/platform_pd.cc

@@ -29,7 +29,7 @@
 #include <fiasco/syscall.h>
 
 using namespace Fiasco;
-using namespace Core;
+using namespace Genode;
 
 
 static bool _init = false;
@@ -37,8 +37,7 @@ static bool _init = false;
 
 void Platform_pd::init()
 {
-	if (_init)
-		return;
+	if (_init) return;
 
 	unsigned i;
 	Pd_alloc reserved(true, true, 0);
@@ -53,6 +52,10 @@ void Platform_pd::init()
 }
 
 
+/****************************
+ ** Private object members **
+ ****************************/
+
 void Platform_pd::_create_pd(bool syscall)
 {
 	enum { TASK_ID_MASK     = (1 << 11) - 1,
@@ -132,27 +135,97 @@ void Platform_pd::_free_pd()
 }
 
 
-Platform_pd::Alloc_thread_id_result Platform_pd::alloc_thread_id(Platform_thread &thread)
+void Platform_pd::_init_threads()
 {
-	for (unsigned i = 0; i < THREAD_MAX; i++) {
-		if (_threads[i] == nullptr) {
-			_threads[i] = &thread;
-			return Thread_id { i };
-		}
-	}
-	return Alloc_thread_id_error::EXHAUSTED;
+	unsigned i;
+
+	for (i = 0; i < THREAD_MAX; ++i)
+		_threads[i] = 0;
 }
 
 
-void Platform_pd::free_thread_id(Thread_id const id)
+Platform_thread* Platform_pd::_next_thread()
 {
-	if (id.value >= THREAD_MAX)
-		return;
+	unsigned i;
 
-	if (!_threads[id.value])
-		warning("double-free of thread ", Hex(_pd_id), ".", Hex(id.value), " detected");
+	/* look for bound thread */
+	for (i = 0; i < THREAD_MAX; ++i)
+		if (_threads[i]) break;
 
-	_threads[id.value] = nullptr;
+	/* no bound threads */
+	if (i == THREAD_MAX) return 0;
+
+	return _threads[i];
+}
+
+
+int Platform_pd::_alloc_thread(int thread_id, Platform_thread &thread)
+{
+	int i = thread_id;
+
+	/* look for free thread */
+	if (thread_id == Platform_thread::THREAD_INVALID) {
+		for (i = 0; i < THREAD_MAX; ++i)
+			if (!_threads[i]) break;
+
+		/* no free threads available */
+		if (i == THREAD_MAX) return -1;
+	} else {
+		if (_threads[i]) return -2;
+	}
+
+	_threads[i] = &thread;
+
+	return i;
+}
+
+
+void Platform_pd::_free_thread(int thread_id)
+{
+	if (!_threads[thread_id])
+		warning("double-free of thread ", Hex(_pd_id), ".", Hex(thread_id), " detected");
+
+	_threads[thread_id] = 0;
+}
+
+
+/***************************
+ ** Public object members **
+ ***************************/
+
+bool Platform_pd::bind_thread(Platform_thread &thread)
+{
+	/* thread_id is THREAD_INVALID by default - only core is the special case */
+	int thread_id = thread.thread_id();
+	l4_threadid_t l4_thread_id;
+
+	int t = _alloc_thread(thread_id, thread);
+	if (t < 0) {
+		error("thread alloc failed");
+		return false;
+	}
+	thread_id = t;
+
+	enum { LTHREAD_MASK = (1 << 7) - 1 };
+
+	l4_thread_id = _l4_task_id;
+	l4_thread_id.id.lthread = thread_id & LTHREAD_MASK;
+
+	/* finally inform thread about binding */
+	thread.bind(thread_id, l4_thread_id, *this);
+
+	return true;
+}
+
+
+void Platform_pd::unbind_thread(Platform_thread &thread)
+{
+	int thread_id = thread.thread_id();
+
+	/* unbind thread before proceeding */
+	thread.unbind();
+
+	_free_thread(thread_id);
 }
 
 
@@ -172,13 +245,15 @@ void Platform_pd::flush(addr_t, size_t size, Core_local_addr core_local_base)
 		               L4_FP_FLUSH_PAGE);
 }
 
-
 Platform_pd::Platform_pd(Allocator &, char const *)
 {
 	/* check correct init */
 	if (!_init)
 		panic("init pd facility via Platform_pd::init() before using it!");
 
+	/* init threads */
+	_init_threads();
+
 	int ret = _alloc_pd(PD_INVALID);
 	if (ret < 0) {
 		panic("pd alloc failed");
@@ -194,6 +269,9 @@ Platform_pd::Platform_pd(char const *, signed pd_id)
 	if (!_init)
 		panic("init pd facility via Platform_pd::init() before using it!");
 
+	/* init threads */
+	_init_threads();
+
 	int ret = _alloc_pd(pd_id);
 	if (ret < 0) {
 		panic("pd alloc failed");
@@ -205,11 +283,10 @@ Platform_pd::Platform_pd(char const *, signed pd_id)
 
 Platform_pd::~Platform_pd()
 {
-	bool any_thread_exists = false;
-	for (Platform_thread *t : _threads) any_thread_exists |= (t != nullptr);
-	if (any_thread_exists)
-		error("attempt to destruct platform PD before threads");
+	/* unbind all threads */
+	while (Platform_thread *t = _next_thread()) unbind_thread(*t);
 
 	_destroy_pd();
 	_free_pd();
 }
+

repos/base-fiasco/src/core/platform_thread.cc

@@ -15,6 +15,8 @@
  */
 
 /* Genode includes */
+#include <base/log.h>
+#include <util/string.h>
 #include <cpu_session/cpu_session.h>
 
 /* core includes */
@@ -26,17 +28,14 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 using namespace Fiasco;
 
 
-void Platform_thread::start(void *ip, void *sp)
+int Platform_thread::start(void *ip, void *sp)
 {
-	if (_id.failed())
-		 return;
-
 	l4_umword_t dummy, old_eflags;
-	l4_threadid_t thread      = native_thread_id();
+	l4_threadid_t thread      = _l4_thread_id;
 	l4_threadid_t pager       = _pager
 	                          ? Capability_space::ipc_cap_data(_pager->cap()).dst
 	                          : L4_INVALID_ID;
@@ -48,47 +47,38 @@ void Platform_thread::start(void *ip, void *sp)
 	                      &old_eflags, &dummy, &dummy,
 	                      0, l4_utcb_get());
 	if (old_eflags == ~0UL)
-		warning("start ", _name, ": old eflags == ~0 on ex_regs ",
+		warning("old eflags == ~0 on ex_regs ",
 		        Hex(thread.id.task), ".", Hex(thread.id.lthread));
 
 	fiasco_register_thread_name(thread, _name.string());
+	return 0;
 }
 
 
-Thread_state Platform_thread::state()
+void Platform_thread::pause()
 {
-	Thread_state s { };
-
-	l4_umword_t   old_eflags, ip, sp;
-	l4_threadid_t thread      = native_thread_id();
-	l4_threadid_t pager       = L4_INVALID_ID;
-	l4_threadid_t preempter   = L4_INVALID_ID;
-	l4_threadid_t cap_handler = L4_INVALID_ID;
-
-	l4_inter_task_ex_regs(thread, ~0UL, ~0UL,
-	                      &preempter, &pager, &cap_handler,
-	                      &old_eflags, &ip, &sp,
-	                      L4_THREAD_EX_REGS_NO_CANCEL, l4_utcb_get());
-	if (old_eflags == ~0UL)
-		warning("state old eflags == ~0 on ex_regs ",
-		        Hex(thread.id.task), ".", Hex(thread.id.lthread));
-
-	/* fill thread state structure */
-	s.cpu.ip = ip;
-	s.cpu.sp = sp;
-	s.state  = Thread_state::State::VALID;
-
-	return s;
+	warning(__func__, " not implemented");
 }
 
 
-Platform_thread::~Platform_thread()
+void Platform_thread::resume()
 {
-	if (_id.failed())
-		return;
+	warning(__func__, " not implemented");
+}
 
+
+void Platform_thread::bind(int thread_id, l4_threadid_t l4_thread_id, Platform_pd &pd)
+{
+	_thread_id    = thread_id;
+	_l4_thread_id = l4_thread_id;
+	_platform_pd  = &pd;
+}
+
+
+void Platform_thread::unbind()
+{
 	l4_umword_t dummy, old_eflags;
-	l4_threadid_t thread      = native_thread_id();
+	l4_threadid_t thread      = _l4_thread_id;
 	l4_threadid_t pager       = thread;
 	l4_threadid_t preempter   = L4_INVALID_ID;
 	l4_threadid_t cap_handler = L4_INVALID_ID;
@@ -105,10 +95,63 @@ Platform_thread::~Platform_thread()
 	                      &old_eflags, &dummy, &dummy,
 	                      0, l4_utcb_get());
 	if (old_eflags == ~0UL)
-		warning("unbind old eflags == ~0 on ex_regs ",
+		warning("old eflags == ~0 on ex_regs ",
 		        Hex(thread.id.task), ".", Hex(thread.id.lthread));
 
-	_id.with_result(
-		[&] (Platform_pd::Thread_id id) { _pd.free_thread_id(id); },
-		[&] (Platform_pd::Alloc_thread_id_error) { });
+	_thread_id    = THREAD_INVALID;
+	_l4_thread_id = L4_INVALID_ID;
+	_platform_pd  = 0;
+}
+
+
+void Platform_thread::state(Thread_state)
+{
+	warning(__func__, " not implemented");
+	throw Cpu_thread::State_access_failed();
+}
+
+
+Thread_state Platform_thread::state()
+{
+	Thread_state s;
+
+	l4_umword_t   old_eflags, ip, sp;
+	l4_threadid_t thread      = _l4_thread_id;
+	l4_threadid_t pager       = L4_INVALID_ID;
+	l4_threadid_t preempter   = L4_INVALID_ID;
+	l4_threadid_t cap_handler = L4_INVALID_ID;
+
+	l4_inter_task_ex_regs(thread, ~0UL, ~0UL,
+	                      &preempter, &pager, &cap_handler,
+	                      &old_eflags, &ip, &sp,
+	                      L4_THREAD_EX_REGS_NO_CANCEL, l4_utcb_get());
+	if (old_eflags == ~0UL)
+		warning("old eflags == ~0 on ex_regs ",
+		        Hex(thread.id.task), ".", Hex(thread.id.lthread));
+
+	/* fill thread state structure */
+	s.ip = ip;
+	s.sp = sp;
+
+	return s;
+}
+
+
+Platform_thread::Platform_thread(size_t, const char *name, unsigned,
+                                 Affinity::Location, addr_t)
+: _l4_thread_id(L4_INVALID_ID), _name(name) { }
+
+
+Platform_thread::Platform_thread(const char *name)
+: _l4_thread_id(L4_INVALID_ID), _name(name) { }
+
+
+Platform_thread::~Platform_thread()
+{
+	/*
+	 * We inform our protection domain about thread destruction, which will end up in
+	 * Thread::unbind()
+	 */
+	if (_platform_pd)
+		_platform_pd->unbind_thread(*this);
 }

repos/base-fiasco/src/core/ram_dataspace_support.cc

@@ -17,7 +17,7 @@
 /* core includes */
 #include <ram_dataspace_factory.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Ram_dataspace_factory::_export_ram_ds(Dataspace_component &) { }

repos/base-fiasco/src/core/spec/x86/platform_x86.cc

@@ -21,7 +21,7 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 using namespace Fiasco;
 
 

repos/base-fiasco/src/core/thread_start.cc

@@ -20,8 +20,9 @@
 
 /* core includes */
 #include <platform.h>
+#include <core_env.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Thread::_thread_start()
@@ -33,18 +34,18 @@ void Thread::_thread_start()
 }
 
 
-Thread::Start_result Thread::start()
+void Thread::start()
 {
 	/* create and start platform thread */
 	native_thread().pt = new (platform().core_mem_alloc())
-		Platform_thread(platform_specific().core_pd(), _stack->name().string());
+		Platform_thread(_stack->name().string());
+
+	platform_specific().core_pd().bind_thread(*native_thread().pt);
 
 	native_thread().pt->pager(platform_specific().core_pager());
 	native_thread().l4id = native_thread().pt->native_thread_id();
 
 	native_thread().pt->start((void *)_thread_start, stack_top());
-
-	return Start_result::OK;
 }
 
 

repos/base-fiasco/src/include/base/internal/native_thread.h

@@ -20,9 +20,11 @@
 /* L4/Fiasco includes */
 #include <fiasco/syscall.h>
 
-namespace Core { struct Platform_thread; }
+namespace Genode {
 
-namespace Genode { struct Native_thread; }
+	struct Platform_thread;
+	struct Native_thread;
+}
 
 
 struct Genode::Native_thread
@@ -36,7 +38,7 @@ struct Genode::Native_thread
 	 * thread object, which is going to be destroyed on destruction of the
 	 * 'Thread'.
 	 */
-	Core::Platform_thread *pt;
+	Platform_thread *pt;
 };
 
 #endif /* _INCLUDE__BASE__INTERNAL__NATIVE_THREAD_H_ */

repos/base-fiasco/src/include/base/internal/rpc_destination.h

@@ -19,7 +19,7 @@
 
 namespace Genode {
 
-	using Rpc_destination = Fiasco::l4_threadid_t;
+	typedef Fiasco::l4_threadid_t Rpc_destination;
 
 	static inline Rpc_destination invalid_rpc_destination()
 	{

repos/base-fiasco/src/lib/base/ipc.cc

@@ -14,6 +14,7 @@
 /* Genode includes */
 #include <base/log.h>
 #include <base/ipc.h>
+#include <base/blocking.h>
 
 /* base-internal includes */
 #include <base/internal/ipc_server.h>
@@ -165,6 +166,10 @@ Rpc_exception_code Genode::ipc_call(Native_capability dst,
 	rcv_header.extract_caps(rcv_msg);
 
 	if (L4_IPC_IS_ERROR(ipc_result)) {
+
+		if (L4_IPC_ERROR(ipc_result) == L4_IPC_RECANCELED)
+			throw Genode::Blocking_canceled();
+
 		error("ipc_call error ", Hex(L4_IPC_ERROR(ipc_result)));
 		throw Genode::Ipc_error();
 	}

repos/base-fiasco/src/lib/base/thread_bootstrap.cc

@@ -21,18 +21,11 @@
 using namespace Genode;
 
 
-static Thread_capability main_thread_cap(Thread_capability main_cap = { })
-{
-	static Thread_capability cap = main_cap;
-	return cap;
-}
-
-
 /*****************************
  ** Startup library support **
  *****************************/
 
-void Genode::prepare_init_main_thread() { }
+void prepare_init_main_thread() { }
 
 
 /************
@@ -48,9 +41,3 @@ void Thread::_init_platform_thread(size_t, Type type)
 
 	_thread_cap = main_thread_cap();
 }
-
-
-void Genode::init_thread_bootstrap(Cpu_session &, Thread_capability main_cap)
-{
-	main_thread_cap(main_cap);
-}

repos/base-fiasco/src/timer/fiasco/component.cc

@@ -1,417 +0,0 @@
-/*
- * \brief  Timer driver for L4/Fiasco
- * \author Norman Feske
- * \author Alexander Boettcher
- * \date   2024-06-14
- */
-
-/*
- * Copyright (C) 2024 Genode Labs GmbH
- *
- * This file is part of the Genode OS framework, which is distributed
- * under the terms of the GNU Affero General Public License version 3.
- */
-
-/* Genode includes */
-#include <base/component.h>
-#include <base/heap.h>
-#include <base/session_object.h>
-#include <base/attached_rom_dataspace.h>
-#include <root/component.h>
-#include <timer_session/timer_session.h>
-
-/* base-internal includes */
-#include <base/internal/alarm_registry.h>
-
-/* L4/Fiasco includes */
-
-#pragma GCC diagnostic push
-#pragma GCC diagnostic ignored "-Wconversion"
-
-namespace Fiasco {
-	#include <l4/sys/ipc.h>
-	#include <l4/sys/kip.h>
-	#include <l4/sys/kernel.h>
-}
-
-#pragma GCC diagnostic pop
-
-
-using namespace Fiasco;
-
-
-namespace Timer {
-
-	using namespace Genode;
-
-	struct Tsc { uint64_t tsc; };
-	struct Clock;
-	struct Device;
-	struct Alarm;
-	struct Root;
-	struct Session_component;
-	struct Main;
-
-	using Alarms = Alarm_registry<Alarm, Clock>;
-}
-
-
-struct Timer::Clock
-{
-	uint64_t us;
-
-	static constexpr uint64_t MASK = uint64_t(-1);
-
-	uint64_t value() const { return us; }
-
-	void print(Output &out) const { Genode::print(out, us); }
-};
-
-
-class Timer::Device
-{
-	private:
-
-		Attached_rom_dataspace const _kip_ds;
-
-	public:
-
-		struct Wakeup_dispatcher : Interface
-		{
-			virtual void dispatch_device_wakeup() = 0;
-		};
-
-		struct Deadline : Clock { };
-
-		static constexpr Deadline infinite_deadline { uint64_t(-1) };
-
-	private:
-
-		struct Waiter : Thread
-		{
-			l4_timeout_s mus_to_timeout(uint64_t const mus) const
-			{
-				if (mus == 0)
-					return L4_IPC_TIMEOUT_0;
-				else if (mus == ~0ULL)
-					return L4_IPC_TIMEOUT_NEVER;
-
-				long e = Genode::log2((unsigned long)mus) - 7;
-
-				if (e < 0) e = 0;
-
-				uint64_t m = mus / (1UL << e);
-
-				enum { M_MASK = 0x3ff };
-
-				/* check corner case */
-				if ((e > 31 ) || (m > M_MASK)) {
-					Genode::warning("invalid timeout ", mus, ", using max. values");
-					e = 0;
-					m = M_MASK;
-				}
-
-				return l4_timeout_rel(m & M_MASK, (unsigned)e);
-			}
-
-			Wakeup_dispatcher &_dispatcher;
-
-			Mutex    _mutex    { }; /* protect '_deadline' */
-			Deadline _deadline { ~0ULL };
-
-			l4_threadid_t _myself { };
-
-			Device  &_device;
-
-			Waiter(Env &env, Wakeup_dispatcher &dispatcher, Device &device)
-			:
-				Thread(env, "waiter", 8*1024*sizeof(addr_t)),
-				_dispatcher(dispatcher),
-				_device(device)
-			{
-				start();
-			}
-
-			void entry() override
-			{
-				_myself = l4_myself();
-
-				for (;;) {
-
-					auto deadline_atomic = [&]
-					{
-						Mutex::Guard guard(_mutex);
-						return _deadline;
-					};
-
-					{
-						auto const deadline = deadline_atomic();
-						auto const now      = _device.now();
-
-						if (now.us < deadline.us) {
-							auto usecs = min(deadline.us - now.us,
-							                 100ull * 1000 * 1000);
-
-							l4_ipc_sleep(l4_timeout(L4_IPC_TIMEOUT_NEVER,
-							                        mus_to_timeout(usecs)));
-						}
-					}
-
-					if (_device.now().us >= deadline_atomic().us)
-						_dispatcher.dispatch_device_wakeup();
-				}
-			}
-
-			void update_deadline(Deadline const deadline)
-			{
-				Mutex::Guard guard(_mutex);
-
-				bool const sooner_than_scheduled = (deadline.us < _deadline.us);
-
-				_deadline = deadline;
-
-				if (sooner_than_scheduled) {
-					/* cancel old timeout by waking sleeping waiter */
-					l4_umword_t   dummy     { };
-					l4_threadid_t preempter { L4_INVALID_ID };
-					l4_threadid_t pager     { L4_INVALID_ID };
-
-					l4_thread_ex_regs_flags(_myself, ~0UL, ~0UL,
-					                        &preempter, &pager, &dummy, &dummy,
-					                        &dummy, 0 /* flags */);
-				}
-			}
-		} _waiter;
-
-	public:
-
-		Device(Env &env, Wakeup_dispatcher &dispatcher)
-		: _kip_ds(env, "l4v2_kip"), _waiter(env, dispatcher, *this) { }
-
-		Clock now() const
-		{
-			auto const kip = _kip_ds.local_addr<Fiasco::l4_kernel_info_t>();
-			return { .us = kip->clock };
-		}
-
-		void update_deadline(Deadline deadline) {
-			_waiter.update_deadline(deadline); }
-};
-
-
-struct Timer::Alarm : Alarms::Element
-{
-	Session_component &session;
-
-	Alarm(Alarms &alarms, Session_component &session, Clock time)
-	:
-		Alarms::Element(alarms, *this, time), session(session)
-	{ }
-
-	void print(Output &out) const;
-};
-
-
-static Timer::Device::Deadline next_deadline(Timer::Alarms &alarms)
-{
-	using namespace Timer;
-
-	return alarms.soonest(Clock { 0 }).convert<Device::Deadline>(
-		[&] (Clock soonest) -> Device::Deadline {
-
-			/* scan alarms for a cluster nearby the soonest */
-			uint64_t const MAX_DELAY_US = 250;
-			Device::Deadline result { soonest.us };
-			alarms.for_each_in_range(soonest, Clock { soonest.us + MAX_DELAY_US },
-			[&] (Alarm const &alarm) {
-				result.us = max(result.us, alarm.time.us); });
-
-			return result;
-		},
-		[&] (Alarms::None) { return Device::infinite_deadline; });
-}
-
-
-struct Timer::Session_component : Session_object<Timer::Session, Session_component>
-{
-	Alarms &_alarms;
-	Mutex  &_alarms_mutex;
-	Device &_device;
-
-	Signal_context_capability _sigh { };
-
-	Clock const _creation_time = _device.now();
-
-	uint64_t _local_now_us() const { return _device.now().us - _creation_time.us; }
-
-	struct Period { uint64_t us; };
-
-	Constructible<Period> _period { };
-	Constructible<Alarm>  _alarm  { };
-
-	Session_component(Env             &env,
-	                  Resources const &resources,
-	                  Label     const &label,
-	                  Diag      const &diag,
-	                  Alarms          &alarms,
-	                  Mutex           &alarms_mutex,
-	                  Device          &device)
-	:
-		Session_object(env.ep(), resources, label, diag),
-		_alarms(alarms), _alarms_mutex(alarms_mutex), _device(device)
-	{ }
-
-	~Session_component()
-	{
-		Mutex::Guard guard(_alarms_mutex);
-
-		_alarm.destruct();
-	}
-
-	/**
-	 * Called by Device::Wakeup_dispatcher with '_alarms_mutex' taken
-	 */
-	void handle_wakeup()
-	{
-		if (_sigh.valid())
-			Signal_transmitter(_sigh).submit();
-
-		if (_period.constructed()) {
-			Clock const next = _alarm.constructed()
-			                 ? Clock { _alarm->time.us  + _period->us }
-			                 : Clock { _device.now().us + _period->us };
-
-			_alarm.construct(_alarms, *this, next);
-
-		} else /* response of 'trigger_once' */ {
-			_alarm.destruct();
-		}
-	}
-
-	/******************************
-	 ** Timer::Session interface **
-	 ******************************/
-
-	void trigger_once(uint64_t rel_us) override
-	{
-		Mutex::Guard guard(_alarms_mutex);
-
-		_period.destruct();
-		_alarm.destruct();
-
-		Clock const now = _device.now();
-
-		rel_us = max(rel_us, 250u);
-		_alarm.construct(_alarms, *this, Clock { now.us + rel_us });
-
-		_device.update_deadline(next_deadline(_alarms));
-	}
-
-	void trigger_periodic(uint64_t period_us) override
-	{
-		Mutex::Guard guard(_alarms_mutex);
-
-		_period.destruct();
-		_alarm.destruct();
-
-		if (period_us) {
-			period_us = max(period_us, 1000u);
-			_period.construct(period_us);
-			handle_wakeup();
-		}
-
-		_device.update_deadline(next_deadline(_alarms));
-	}
-
-	void sigh(Signal_context_capability sigh) override { _sigh = sigh; }
-
-	uint64_t elapsed_ms() const override { return _local_now_us()/1000; }
-	uint64_t elapsed_us() const override { return _local_now_us(); }
-
-	void msleep(uint64_t) override { }
-	void usleep(uint64_t) override { }
-};
-
-
-struct Timer::Root : public Root_component<Session_component>
-{
-	private:
-
-		Env    &_env;
-		Alarms &_alarms;
-		Mutex  &_alarms_mutex;
-		Device &_device;
-
-	protected:
-
-		Session_component *_create_session(const char *args) override
-		{
-			return new (md_alloc())
-				Session_component(_env,
-				                  session_resources_from_args(args),
-				                  session_label_from_args(args),
-				                  session_diag_from_args(args),
-				                  _alarms, _alarms_mutex, _device);
-		}
-
-		void _upgrade_session(Session_component *s, const char *args) override
-		{
-			s->upgrade(ram_quota_from_args(args));
-			s->upgrade(cap_quota_from_args(args));
-		}
-
-		void _destroy_session(Session_component *session) override
-		{
-			Genode::destroy(md_alloc(), session);
-		}
-
-	public:
-
-		Root(Env &env, Allocator &md_alloc,
-		     Alarms &alarms, Mutex &alarms_mutex, Device &device)
-		:
-			Root_component<Session_component>(&env.ep().rpc_ep(), &md_alloc),
-			_env(env), _alarms(alarms), _alarms_mutex(alarms_mutex), _device(device)
-		{ }
-};
-
-
-void Timer::Alarm::print(Output &out) const { Genode::print(out, session.label()); }
-
-
-struct Timer::Main : Device::Wakeup_dispatcher
-{
-	Env &_env;
-
-	Device _device { _env, *this };
-
-	Mutex  _alarms_mutex { };
-	Alarms _alarms { };
-
-	Sliced_heap _sliced_heap { _env.ram(), _env.rm() };
-
-	Root _root { _env, _sliced_heap, _alarms, _alarms_mutex, _device };
-
-	/**
-	 * Device::Wakeup_dispatcher
-	 */
-	void dispatch_device_wakeup() override
-	{
-		Mutex::Guard guard(_alarms_mutex);
-
-		/* handle and remove pending alarms */
-		while (_alarms.with_any_in_range({ 0 }, _device.now(), [&] (Alarm &alarm) {
-			alarm.session.handle_wakeup(); }));
-
-		/* schedule next wakeup */
-		_device.update_deadline(next_deadline(_alarms));
-	}
-
-	Main(Genode::Env &env) : _env(env)
-	{
-		_env.parent().announce(_env.ep().manage(_root));
-	}
-};
-
-
-void Component::construct(Genode::Env &env) { static Timer::Main inst(env); }

repos/base-fiasco/src/timer/fiasco/target.mk

@@ -1,6 +1,9 @@
-TARGET   = fiasco_timer
-INC_DIR += $(PRG_DIR)
-SRC_CC  += component.cc
-LIBS    += base syscall-fiasco
+TARGET   = fiasco_timer_drv
+LIBS    += syscall-fiasco
+GEN_DIR := $(dir $(call select_from_repositories,src/timer/main.cc))
+INC_DIR += $(GEN_DIR)/periodic
+SRC_CC  += periodic/time_source.cc fiasco/time_source.cc
 
-REP_INC_DIR += src/include
+vpath %.cc $(GEN_DIR)
+
+include $(GEN_DIR)/target.inc

repos/base-foc/include/foc/thread_state.h

@@ -25,9 +25,14 @@ namespace Genode { struct Foc_thread_state; }
 
 struct Genode::Foc_thread_state : Thread_state
 {
-	Foc::l4_cap_idx_t  kcap { Foc::L4_INVALID_CAP }; /* thread's gate cap in its PD */
-	uint32_t           id   { };                     /* ID of gate capability */
-	addr_t             utcb { };                     /* thread's UTCB in its PD */
+	Foc::l4_cap_idx_t  kcap;         /* thread's gate cap in its PD */
+	uint16_t           id;           /* ID of gate capability */
+	addr_t             utcb;         /* thread's UTCB in its PD */
+
+	/**
+	 * Constructor
+	 */
+	Foc_thread_state() : kcap(Foc::L4_INVALID_CAP), id(0), utcb(0) { }
 };
 
 #endif /* _INCLUDE__FOC__THREAD_STATE_H_ */

repos/base-foc/lib/mk/base-foc-common.inc

@@ -13,3 +13,4 @@ SRC_CC += rpc_dispatch_loop.cc
 SRC_CC += thread.cc thread_bootstrap.cc thread_myself.cc utcb.cc
 SRC_CC += capability.cc
 SRC_CC += signal_source_client.cc
+SRC_CC += platform.cc

repos/base-foc/lib/mk/base-foc.inc

@@ -4,7 +4,6 @@ LIBS   += base-foc-common syscall-foc cxx
 
 SRC_CC += cap_map_remove.cc cap_alloc.cc
 SRC_CC += cache.cc
-SRC_CC += capability_slab.cc
 SRC_CC += thread_start.cc
 SRC_CC += signal_transmitter.cc signal.cc
 SRC_CC += stack_area_addr.cc

repos/base-foc/patches/0010-L4RE-get-rid-of-__builtin_strlen-usage.patch

@@ -11,11 +11,10 @@ diff --git a/l4/pkg/l4re-core/l4sys/include/kdebug.h b/l4/pkg/l4re-core/l4sys/in
 index cfb17464..64ee9900 100644
 --- a/l4/pkg/l4re-core/l4sys/include/kdebug.h
 +++ b/l4/pkg/l4re-core/l4sys/include/kdebug.h
-@@ -133,6 +133,14 @@ __kdebug_op_1(unsigned op, l4_mword_t val) L4_NOTHROW
+@@ -133,6 +133,13 @@ __kdebug_op_1(unsigned op, l4_mword_t val) L4_NOTHROW
    return res;
  }
  
-+__attribute__((optimize("no-tree-loop-distribute-patterns")))
 +L4_INLINE unsigned __kdebug_strlen(char const * s)
 +{
 +	unsigned r = 0;

repos/base-foc/patches/0018-L4-enable-gcc_10.patch

@@ -0,0 +1,15 @@
+L4: enable GCC 10
+
+diff --git a/l4/mk/Makeconf b/l4/mk/Makeconf
+index eb59b51..a7b5955 100644
+--- a/l4/mk/Makeconf
++++ b/l4/mk/Makeconf
+@@ -52,7 +52,7 @@ L4_KIP_OFFS_SYS_DEBUGGER = 0x900
+ L4_STACK_ADDR           ?= $(L4_STACK_ADDR_$(ARCH))
+ L4_STACK_SIZE           ?= $(if $(L4_STACK_SIZE_MAIN_THREAD),$(L4_STACK_SIZE_MAIN_THREAD),0x8000)
+ 
+-CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9
++CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9 10
+ CC_WHITELIST-clang   := 3.5 3.6 3.7 3.8 3.9
+ 
+ # This is quite bad: There is no other chance to disable the page-alignedment

repos/base-foc/patches/0018-L4-enable-gcc_12.patch

@@ -1,15 +0,0 @@
-L4: enable GCC 12
-
-diff --git a/l4/mk/Makeconf b/l4/mk/Makeconf
-index eb59b51..a7b5955 100644
---- a/l4/mk/Makeconf
-+++ b/l4/mk/Makeconf
-@@ -52,7 +52,7 @@ L4_KIP_OFFS_SYS_DEBUGGER = 0x900
- L4_STACK_ADDR           ?= $(L4_STACK_ADDR_$(ARCH))
- L4_STACK_SIZE           ?= $(if $(L4_STACK_SIZE_MAIN_THREAD),$(L4_STACK_SIZE_MAIN_THREAD),0x8000)
- 
--CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9
-+CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9 10 11 12
- CC_WHITELIST-clang   := 3.5 3.6 3.7 3.8 3.9
- 
- # This is quite bad: There is no other chance to disable the page-alignedment

repos/base-foc/patches/0021-FOC-enable-gcc_10.patch

@@ -0,0 +1,15 @@
+FOC: enable GCC 10
+
+diff --git a/src/Makeconf b/src/Makeconf
+index de5b656..7660daa 100644
+--- a/src/Makeconf
++++ b/src/Makeconf
+@@ -244,7 +244,7 @@ ifeq ($(CC_TYPE),gcc)
+ endif
+ 
+ 
+-CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9
++CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9 10
+ CC_WHITELIST-clang   := 3.6 3.7 3.8 3.9 4.0 5.0 6.0 7.0 8.0 9.0
+ CC_WHITELIST         := $(CC_WHITELIST-$(CC_TYPE))
+ 

repos/base-foc/patches/0021-FOC-enable-gcc_12.patch

@@ -1,15 +0,0 @@
-FOC: enable GCC 12
-
-diff --git a/src/Makeconf b/src/Makeconf
-index de5b656..7660daa 100644
---- a/src/Makeconf
-+++ b/src/Makeconf
-@@ -244,7 +244,7 @@ ifeq ($(CC_TYPE),gcc)
- endif
- 
- 
--CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9
-+CC_WHITELIST-gcc     := 4.7 4.8 4.9 5 6 7 8 9 10 11 12
- CC_WHITELIST-clang   := 3.6 3.7 3.8 3.9 4.0 5.0 6.0 7.0 8.0 9.0
- CC_WHITELIST         := $(CC_WHITELIST-$(CC_TYPE))
- 

repos/base-foc/patches/0024-FOC-ia32-add-implementation-for-__udivmoddi4.patch

@@ -1,94 +0,0 @@
-From 8d55cdc73b07dd56ae59a42bcc11cde82614334a Mon Sep 17 00:00:00 2001
-From: Frank Mehnert <frank.mehnert@kernkonzept.com>
-Date: Mon, 10 May 2021 00:00:00 +0000
-Subject: [PATCH] ia32: add implementation for '__udivmoddi4()'
-
-This function is implicitly required by code in jdb.cpp performing a
-64-bit integer division on 32-bit systems. This function is required
-by code generated with gcc-11. Code generated with older versions of
-gcc was satisfied with the existing implementation for '__udivdi3'.
-
-Also fix cosmetic issues in gcc_lib.c and add Doxygen documentation.
-
-Change-Id: If5b44a9e98429c4fc3eacdd5af8bdaf33c9c2a8f
----
- src/lib/libk/gcc_lib.c | 49 +++++++++++++++++++++++++++++++++++-------
- 1 file changed, 41 insertions(+), 8 deletions(-)
-
-diff --git a/src/lib/libk/gcc_lib.c b/src/lib/libk/gcc_lib.c
-index e5626145..b121cb63 100644
---- a/src/lib/libk/gcc_lib.c
-+++ b/src/lib/libk/gcc_lib.c
-@@ -1,6 +1,8 @@
- 
- unsigned long long __umoddi3(unsigned long long, unsigned long long);
- unsigned long long __udivdi3(unsigned long long, unsigned long long);
-+unsigned long long __udivmoddi4(unsigned long long, unsigned long long,
-+                                unsigned long long *);
- 
- struct llmoddiv_t
- {
-@@ -31,15 +33,15 @@ static struct llmoddiv_t llmoddiv(unsigned long long div, unsigned long long s)
-   while (1)
-     {
-       if (div >= s)
--	{
--	  div -= s;
--	  i |= tmp;
--	}
-+        {
-+          div -= s;
-+          i |= tmp;
-+        }
-       if (div == 0)
--	break;
-+        break;
-       tmp >>= 1;
-       if (!tmp)
--	break;
-+        break;
-       s >>= 1;
-     }
- 
-@@ -47,8 +49,39 @@ static struct llmoddiv_t llmoddiv(unsigned long long div, unsigned long long s)
- }
- 
- 
-+/**
-+ * 64-bit unsigned modulo for 32-bit machines.
-+ *
-+ * \param div  Dividend.
-+ * \param s    Divisor.
-+ * \return div / s.
-+ */
- unsigned long long __umoddi3(unsigned long long div, unsigned long long s)
--{ return llmoddiv(div,s).mod; }
-+{ return llmoddiv(div, s).mod; }
- 
-+/**
-+ * 64-bit unsigned division for 32-bit machines.
-+ *
-+ * \param div  Dividend.
-+ * \param s    Divisor.
-+ * \return div / s.
-+ */
- unsigned long long __udivdi3(unsigned long long div, unsigned long long s)
--{ return llmoddiv(div,s).div; }
-+{ return llmoddiv(div, s).div; }
-+
-+/**
-+ * 64-bit unsigned division + modulo for 32-bit machines.
-+ *
-+ * \param n       Dividend.
-+ * \param d       Divisor.
-+ * \param[out] r  Pointer to the result holding div % s.
-+ * \return div / s.
-+ */
-+unsigned long long __udivmoddi4(unsigned long long div, unsigned long long s,
-+                                unsigned long long *r)
-+{
-+  struct llmoddiv_t md = llmoddiv(div, s);
-+  if (r)
-+    *r = md.mod;
-+  return md.div;
-+}

repos/base-foc/patches/0025-FOC-no-tree-loop-distribute-patterns.patch

@@ -1,17 +0,0 @@
-Fix reboot loop when built with GCC 12.
-
-diff --git a/src/Makeconf b/src/Makeconf
-index bb7ad16c..2fe11226 100644
---- a/src/Makeconf
-+++ b/src/Makeconf
-@@ -167,8 +167,8 @@ NOOPT_SHARED_FLAGS += $(NOOPT_SHARED_FLAGS-$(CC_TYPE))
- # Standard compile flags
- ASFLAGS		+= $(SHARED_FLAGS) -DASSEMBLER
- ASFLAGS-clang	+= -no-integrated-as
--CFLAGS		+= $(SHARED_FLAGS) -Wbad-function-cast -Wstrict-prototypes
--CXXFLAGS	+= $(SHARED_FLAGS) -fno-rtti -fno-exceptions
-+CFLAGS		+= $(SHARED_FLAGS) -Wbad-function-cast -Wstrict-prototypes -fno-tree-loop-distribute-patterns
-+CXXFLAGS	+= $(SHARED_FLAGS) -fno-rtti -fno-exceptions -fno-tree-loop-distribute-patterns
- OPT_CFLAGS	+= $(OPT_SHARED_FLAGS)
- OPT_CXXFLAGS	+= $(OPT_SHARED_FLAGS)
- NOOPT_CFLAGS	+= $(NOOPT_SHARED_FLAGS)

repos/base-foc/ports/foc.hash

@@ -1 +1 @@
-00cfb7994fee75bb5aae010a3d2c16a7ffd29ec9
+abe2de76835f33297ca4e4ac687e69bc04f83dc5

repos/base-foc/ports/foc.port

@@ -37,13 +37,11 @@ PATCH_OPT(patches/0014-Always-enable-user-mode-access-for-performance-monit.patc
 PATCH_OPT(patches/0015-VMX-disable-event-injection-if-requested-by-VMM.patch)     := -p3 -d${DIR(foc)}
 PATCH_OPT(patches/0016-svm-provide-cr0-to-guest-if-np-enabled.patch)              := -p3 -d${DIR(foc)}
 PATCH_OPT(patches/0017-svm-avoid-forceful-exit-on-task-switch.patch)              := -p3 -d${DIR(foc)}
-PATCH_OPT(patches/0018-L4-enable-gcc_12.patch)                                    := -p2 -d${DIR(mk)}
+PATCH_OPT(patches/0018-L4-enable-gcc_10.patch)                                    := -p2 -d${DIR(mk)}
 PATCH_OPT(patches/0019-Bootstrap-do-not-depend-on-any-libstdcxx-feature.patch)    := -p1 -d${DIR(bootstrap)}
 PATCH_OPT(patches/0020-Bootstrap-fix-amd64-build-with-binutils-2_32.patch)        := -p1 -d${DIR(bootstrap)}
-PATCH_OPT(patches/0021-FOC-enable-gcc_12.patch)                                   := -p1 -d${DIR(foc)}
+PATCH_OPT(patches/0021-FOC-enable-gcc_10.patch)                                   := -p1 -d${DIR(foc)}
 PATCH_OPT(patches/0022-FOC-amd64-split-_syscall_entry-into-code-and-data.patch)   := -p1 -d${DIR(foc)}
 PATCH_OPT(patches/0023-FOC-arm-link-bootstrap-as-et_rel.patch)                    := -p1 -d${DIR(foc)}
-PATCH_OPT(patches/0024-FOC-ia32-add-implementation-for-__udivmoddi4.patch)        := -p1 -d${DIR(foc)}
-PATCH_OPT(patches/0025-FOC-no-tree-loop-distribute-patterns.patch)                := -p1 -d${DIR(foc)}
 
 $(call check_tool,gawk)

repos/base-foc/recipes/src/base-foc-imx6q_sabrelite/hash

@@ -1 +1 @@
-2024-12-10 4247239f4d3ce9a840be368ac9e054e8064c01c6
+2022-10-11 d258920f8664460c78eeea25fafb89eaa5e7adf5

repos/base-foc/recipes/src/base-foc-imx7d_sabre/hash

@@ -1 +1 @@
-2024-12-10 39609d3553422b8c7c6acff2db845c67c5f8912b
+2022-10-11 1c94d29566bccccced246eeaf90702348e2b1a7f

repos/base-foc/recipes/src/base-foc-pbxa9/hash

@@ -1 +1 @@
-2024-12-10 7867db59531dc9086e76b74800125ee61ccc310e
+2022-10-11 2668fd23d5cbd45b8f632073fc7c155f96ecb848

repos/base-foc/recipes/src/base-foc-pc/hash

@@ -1 +1 @@
-2024-12-10 3fc7c1b2cae2b9af835c97bf384b10411ec9c511
+2022-10-11 8da054ff9e4c37895816fd30857b3c42d9e75eb0

repos/base-foc/recipes/src/base-foc-rpi3/hash

@@ -1 +1 @@
-2024-12-10 68ee5bc5640e1d32c33f46072256d5b1c71bef9b
+2022-10-11 f41df6b57d2c4b090a84427e02950df84fb385ad

repos/base-foc/recipes/src/base-foc_content.inc

@@ -39,4 +39,4 @@ content:
 	for spec in x86_32 x86_64 arm arm_64; do \
 	  mv lib/mk/spec/$$spec/ld-foc.mk lib/mk/spec/$$spec/ld.mk; \
 	  done;
-	sed -i "s/foc_timer/timer/" src/timer/foc/target.mk
+	sed -i "s/foc_timer_drv/timer/" src/timer/foc/target.mk

repos/base-foc/run/cap_integrity.run

@@ -1,4 +1,4 @@
-build { core init lib/ld test/cap_integrity }
+build "core init test/cap_integrity"
 
 create_boot_directory
 
@@ -20,7 +20,7 @@ install_config {
 	</config>
 }
 
-build_boot_image [build_artifacts]
+build_boot_image "core ld.lib.so init test-cap_integrity"
 
 append qemu_args "-nographic "
 

repos/base-foc/src/core/core_log_out.cc

@@ -17,7 +17,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Core_log::out(char const c)

repos/base-foc/src/core/include/cap_id_alloc.h

@@ -20,25 +20,24 @@
 #include <base/mutex.h>
 #include <synced_range_allocator.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core { class Cap_id_allocator; }
+namespace Genode { class Cap_id_allocator; }
 
 
-class Core::Cap_id_allocator
+class Genode::Cap_id_allocator
 {
 	public:
 
-		using id_t = unsigned;
+		using id_t = uint16_t;
+
+		enum { ID_MASK = 0xffff };
 
 	private:
 
 		enum {
-			CAP_ID_OFFSET  = 1 << 2,
-			CAP_ID_MASK    = CAP_ID_OFFSET - 1,
-			CAP_ID_RANGE   = 1u << 28,
-			ID_MASK        = CAP_ID_RANGE - 1,
+			CAP_ID_RANGE   = ~0UL,
+			CAP_ID_MASK    = ~3UL,
+			CAP_ID_NUM_MAX = CAP_ID_MASK >> 2,
+			CAP_ID_OFFSET  = 1 << 2
 		};
 
 		Synced_range_allocator<Allocator_avl> _id_alloc;

repos/base-foc/src/core/include/cap_index.h

@@ -18,18 +18,15 @@
 #include <base/internal/native_thread.h>
 #include <base/internal/cap_map.h>
 
-/* core includes */
-#include <types.h>
+namespace Genode {
 
-namespace Core {
-
-	class Core_cap_index;
 	class Platform_thread;
 	class Pd_session_component;
+	class Core_cap_index;
 }
 
 
-class Core::Core_cap_index : public Native_capability::Data
+class Genode::Core_cap_index : public Native_capability::Data
 {
 	private:
 

repos/base-foc/src/core/include/cap_mapping.h

@@ -16,15 +16,16 @@
 
 /* core includes */
 #include <cap_index.h>
+#include <util/noncopyable.h>
 
-namespace Core { class Cap_mapping; }
+namespace Genode { class Cap_mapping; }
 
 
 /**
  * A Cap_mapping embodies a capability of core, and its mapped
  * copy in another protection domain.
  */
-class Core::Cap_mapping : Noncopyable
+class Genode::Cap_mapping : Noncopyable
 {
 	private:
 

repos/base-foc/src/core/include/ipc_pager.h

@@ -27,16 +27,16 @@
 /* base-internal includes */
 #include <base/internal/native_thread.h>
 
-/* core includes */
+/* core-local includes */
 #include <mapping.h>
 
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-namespace Core { class Ipc_pager; }
+namespace Genode { class Ipc_pager; }
 
 
-class Core::Ipc_pager : public Native_capability
+class Genode::Ipc_pager : public Native_capability
 {
 	public:
 

repos/base-foc/src/core/include/irq_object.h

@@ -20,13 +20,10 @@
 #include <irq_session/irq_session.h>
 #include <cap_index.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core { class Irq_object; }
+namespace Genode { class Irq_object; }
 
 
-class Core::Irq_object
+class Genode::Irq_object
 {
 	private:
 
@@ -59,8 +56,8 @@ class Core::Irq_object
 		uint64_t msi_address() const { return _msi_addr; }
 		addr_t   msi_value()   const { return _msi_data; }
 
-		void sigh(Signal_context_capability cap) { _sig_cap = cap; }
-		void notify() { Signal_transmitter(_sig_cap).submit(1); }
+		void sigh(Genode::Signal_context_capability cap) { _sig_cap = cap; }
+		void notify() { Genode::Signal_transmitter(_sig_cap).submit(1); }
 
 		bool associate(unsigned irq, bool msi, Irq_session::Trigger,
 		               Irq_session::Polarity);

repos/base-foc/src/core/include/map_local.h

@@ -22,7 +22,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-namespace Core {
+namespace Genode {
 
 	/**
 	 * Map pages locally within core

repos/base-foc/src/core/include/native_cpu_component.h

@@ -18,18 +18,15 @@
 #include <base/rpc_server.h>
 #include <foc_native_cpu/foc_native_cpu.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core {
+namespace Genode {
 
 	class Cpu_session_component;
 	class Native_cpu_component;
 }
 
 
-class Core::Native_cpu_component : public Rpc_object<Cpu_session::Native_cpu,
-                                                     Native_cpu_component>
+class Genode::Native_cpu_component : public Rpc_object<Cpu_session::Native_cpu,
+                                                       Native_cpu_component>
 {
 	private:
 

repos/base-foc/src/core/include/pager_object_exception_state.h

@@ -17,10 +17,10 @@
 #include <base/mutex.h>
 #include <foc/thread_state.h>
 
-namespace Core { struct Pager_object_exception_state; }
+namespace Genode { struct Pager_object_exception_state; }
 
 
-struct Core::Pager_object_exception_state
+struct Genode::Pager_object_exception_state
 {
 	Mutex            mutex { };
 	unsigned         exceptions;   /* counts exceptions raised by the thread */

repos/base-foc/src/core/include/platform.h

@@ -21,7 +21,7 @@
 #include <base/synced_allocator.h>
 #include <base/allocator_avl.h>
 
-/* core includes */
+/* Core includes */
 #include <pager.h>
 #include <cap_id_alloc.h>
 #include <platform_generic.h>
@@ -32,10 +32,10 @@
 namespace Foc { struct l4_kernel_info_t; }
 
 
-namespace Core { class Platform; }
+namespace Genode { class Platform; }
 
 
-class Core::Platform : public Platform_generic
+class Genode::Platform : public Platform_generic
 {
 	private:
 
@@ -55,14 +55,13 @@ class Core::Platform : public Platform_generic
 			 */
 			Sigma0(Cap_index*);
 
-			/* never called */
-			Pager_result pager(Ipc_pager &) override { return Pager_result::STOP; }
+			int pager(Ipc_pager &) override { /* never called */ return -1; }
 		};
 
 		/*
 		 * Shortcut for the type of allocator instances for physical resources
 		 */
-		using Phys_allocator = Synced_range_allocator<Allocator_avl>;
+		typedef Synced_range_allocator<Allocator_avl> Phys_allocator;
 
 		Platform_pd     *_core_pd = nullptr; /* core protection domain object */
 		Phys_allocator   _ram_alloc;         /* RAM allocator */
@@ -133,8 +132,7 @@ class Core::Platform : public Platform_generic
 			 */
 			Core_pager(Platform_pd &core_pd, Sigma0 &);
 
-			/* never called */
-			Pager_result pager(Ipc_pager &) override { return Pager_result::STOP; }
+			int pager(Ipc_pager &) override { /* never called */ return -1; }
 		};
 
 		/**

repos/base-foc/src/core/include/platform_pd.h

@@ -36,14 +36,14 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-namespace Core {
+namespace Genode {
 
 	class Platform_thread;
 	class Platform_pd;
 }
 
 
-class Core::Platform_pd : public Address_space
+class Genode::Platform_pd : public Address_space
 {
 	private:
 

repos/base-foc/src/core/include/platform_thread.h

@@ -26,14 +26,14 @@
 #include <cap_mapping.h>
 #include <assertion.h>
 
-namespace Core {
+namespace Genode {
 
 	class Platform_pd;
 	class Platform_thread;
 }
 
 
-class Core::Platform_thread : Interface
+class Genode::Platform_thread : Interface
 {
 	private:
 
@@ -45,7 +45,7 @@ class Core::Platform_thread : Interface
 
 		enum State { DEAD, RUNNING };
 
-		using Name = String<32>;
+		typedef String<32> Name;
 
 		friend class Platform_pd;
 
@@ -60,7 +60,6 @@ class Core::Platform_thread : Interface
 		Platform_pd  *_platform_pd;    /* protection domain thread is bound to */
 		Pager_object *_pager_obj;
 		unsigned      _prio;
-		bool          _bound_to_pd = false;
 
 		Affinity::Location _location { };
 
@@ -75,8 +74,8 @@ class Core::Platform_thread : Interface
 		/**
 		 * Constructor for non-core threads
 		 */
-		Platform_thread(Platform_pd &, Rpc_entrypoint &, Ram_allocator &, Region_map &,
-		                size_t, const char *name, unsigned priority, Affinity::Location, addr_t);
+		Platform_thread(size_t, const char *name, unsigned priority,
+		                Affinity::Location, addr_t);
 
 		/**
 		 * Constructor for core main-thread
@@ -94,18 +93,16 @@ class Core::Platform_thread : Interface
 		 */
 		~Platform_thread();
 
-		/**
-		 * Return true if thread creation succeeded
-		 */
-		bool valid() const { return _bound_to_pd; }
-
 		/**
 		 * Start thread
 		 *
 		 * \param ip  instruction pointer to start at
 		 * \param sp  stack pointer to use
+		 *
+		 * \retval  0  successful
+		 * \retval -1  thread could not be started
 		 */
-		void start(void *ip, void *sp);
+		int start(void *ip, void *sp);
 
 		/**
 		 * Pause this thread
@@ -136,11 +133,15 @@ class Core::Platform_thread : Interface
 
 		/**
 		 * Override thread state with 's'
+		 *
+		 * \throw Cpu_session::State_access_failed
 		 */
 		void state(Thread_state s);
 
 		/**
 		 * Read thread state
+		 *
+		 * \throw Cpu_session::State_access_failed
 		 */
 		Foc_thread_state state();
 
@@ -155,10 +156,10 @@ class Core::Platform_thread : Interface
 		Affinity::Location affinity() const;
 
 		/**
-		 * Turn thread into vCPU
+		 * Make thread to vCPU
 		 */
 		Foc::l4_cap_idx_t setup_vcpu(unsigned, Cap_mapping const &,
-		                             Cap_mapping &, addr_t &);
+		                             Cap_mapping &, Region_map::Local_addr &);
 
 
 		/************************

repos/base-foc/src/core/include/rpc_cap_factory.h

@@ -23,13 +23,10 @@
 /* base-internal includes */
 #include <base/internal/page_size.h>
 
-/* core includes */
-#include <types.h>
 
-namespace Core { class Rpc_cap_factory; }
+namespace Genode { class Rpc_cap_factory; }
 
-
-class Core::Rpc_cap_factory
+class Genode::Rpc_cap_factory
 {
 	private:
 

repos/base-foc/src/core/include/util.h

@@ -18,6 +18,8 @@
 #define _CORE__INCLUDE__UTIL_H_
 
 /* Genode includes */
+#include <base/stdint.h>
+#include <base/log.h>
 #include <rm_session/rm_session.h>
 #include <util/touch.h>
 
@@ -27,10 +29,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-/* core includes */
-#include <types.h>
-
-namespace Core {
+namespace Genode {
 
 	inline void panic(const char *s)
 	{
@@ -45,8 +44,8 @@ namespace Core {
 		unsigned char const volatile *bptr;
 		unsigned char const *eptr;
 
-		bptr = (unsigned char const volatile *)(((addr_t)addr) & L4_PAGEMASK);
-		eptr = (unsigned char const *)(((addr_t)addr + size - 1) & L4_PAGEMASK);
+		bptr = (unsigned char const volatile *)(((Genode::addr_t)addr) & L4_PAGEMASK);
+		eptr = (unsigned char const *)(((Genode::addr_t)addr + size - 1) & L4_PAGEMASK);
 		for ( ; bptr <= eptr; bptr += L4_PAGESIZE)
 			touch_read(bptr);
 	}
@@ -58,8 +57,8 @@ namespace Core {
 		unsigned char volatile *bptr;
 		unsigned char const *eptr;
 
-		bptr = (unsigned char volatile *)(((addr_t)addr) & L4_PAGEMASK);
-		eptr = (unsigned char const *)(((addr_t)addr + size - 1) & L4_PAGEMASK);
+		bptr = (unsigned char volatile *)(((Genode::addr_t)addr) & L4_PAGEMASK);
+		eptr = (unsigned char const *)(((Genode::addr_t)addr + size - 1) & L4_PAGEMASK);
 		for (; bptr <= eptr; bptr += L4_PAGESIZE)
 			touch_read_write(bptr);
 	}
@@ -73,7 +72,7 @@ namespace Core {
 	inline addr_t map_src_addr(addr_t core_local_addr, addr_t) {
 		return core_local_addr; }
 
-	inline Log2 kernel_constrained_map_size(Log2 size) { return size; }
+	inline size_t constrain_map_size_log2(size_t size_log2) { return size_log2; }
 }
 
 #endif /* _CORE__INCLUDE__UTIL_H_ */

repos/base-foc/src/core/include/vm_session_component.h

@@ -28,18 +28,18 @@
 #include <trace/source_registry.h>
 #include <foc_native_vcpu/foc_native_vcpu.h>
 
-namespace Core {
-
+namespace Genode
+{
 	class Vm_session_component;
 	struct Vcpu;
 
 	enum { MAX_VCPU_IDS = (Platform::VCPU_VIRT_EXT_END -
 	                       Platform::VCPU_VIRT_EXT_START) / L4_PAGESIZE };
-	using Vcpu_id_allocator = Bit_allocator<MAX_VCPU_IDS>;
+	typedef Bit_allocator<MAX_VCPU_IDS> Vcpu_id_allocator;
 }
 
 
-struct Core::Vcpu : Rpc_object<Vm_session::Native_vcpu, Vcpu>
+struct Genode::Vcpu : Rpc_object<Vm_session::Native_vcpu, Vcpu>
 {
 	private:
 
@@ -49,7 +49,7 @@ struct Core::Vcpu : Rpc_object<Vm_session::Native_vcpu, Vcpu>
 		Vcpu_id_allocator              &_vcpu_ids;
 		Cap_mapping                     _recall            { true };
 		Foc::l4_cap_idx_t               _task_index_client { };
-		addr_t                          _foc_vcpu_state    { };
+		Region_map::Local_addr          _foc_vcpu_state    { };
 
 	public:
 
@@ -64,12 +64,12 @@ struct Core::Vcpu : Rpc_object<Vm_session::Native_vcpu, Vcpu>
 		 ** Native_vcpu RPC interface **
 		 *******************************/
 
-		Foc::l4_cap_idx_t task_index()     const { return _task_index_client; }
-		addr_t            foc_vcpu_state() const { return _foc_vcpu_state; }
+		Foc::l4_cap_idx_t      task_index()     const { return _task_index_client; }
+		Region_map::Local_addr foc_vcpu_state() const { return _foc_vcpu_state; }
 };
 
 
-class Core::Vm_session_component
+class Genode::Vm_session_component
 :
 	private Ram_quota_guard,
 	private Cap_quota_guard,
@@ -78,8 +78,8 @@ class Core::Vm_session_component
 {
 	private:
 
-		using Con_ram_allocator = Constrained_ram_allocator;
-		using Avl_region        = Allocator_avl_tpl<Rm_region>;
+		typedef Constrained_ram_allocator    Con_ram_allocator;
+		typedef Allocator_avl_tpl<Rm_region> Avl_region;
 
 		Rpc_entrypoint    &_ep;
 		Con_ram_allocator  _constrained_md_ram_alloc;
@@ -93,7 +93,6 @@ class Core::Vm_session_component
 		/* helpers for vm_session_common.cc */
 		void _attach_vm_memory(Dataspace_component &, addr_t, Attach_attr);
 		void _detach_vm_memory(addr_t, size_t);
-		void _with_region(addr_t, auto const &);
 
 	protected:
 
@@ -116,16 +115,15 @@ class Core::Vm_session_component
 		 *********************************/
 
 		/* used on destruction of attached dataspaces */
-		void detach_at         (addr_t)         override;
-		void unmap_region      (addr_t, size_t) override;
-		void reserve_and_flush (addr_t)         override;
+		void detach(Region_map::Local_addr) override; /* vm_session_common.cc */
+		void unmap_region(addr_t, size_t) override;   /* vm_session_common.cc */
 
 
 		/**************************
 		 ** Vm session interface **
 		 **************************/
 
-		Capability<Native_vcpu> create_vcpu(Thread_capability) override;
+		Capability<Native_vcpu> create_vcpu(Thread_capability);
 		void attach_pic(addr_t) override { /* unused on Fiasco.OC */ }
 
 		void attach(Dataspace_capability, addr_t, Attach_attr) override; /* vm_session_common.cc */

repos/base-foc/src/core/io_mem_session_support.cc

@@ -6,7 +6,7 @@
  */
 
 /*
- * Copyright (C) 2006-2024 Genode Labs GmbH
+ * Copyright (C) 2006-2017 Genode Labs GmbH
  *
  * This file is part of the Genode OS framework, which is distributed
  * under the terms of the GNU Affero General Public License version 3.
@@ -18,40 +18,34 @@
 #include <io_mem_session_component.h>
 #include <map_local.h>
 
-using namespace Core;
+using namespace Genode;
 
 
-void Io_mem_session_component::_unmap_local(addr_t base, size_t size, addr_t)
+void Io_mem_session_component::_unmap_local(addr_t base, size_t)
 {
-	if (!base)
-		return;
-
-	unmap_local(base, size >> 12);
 	platform().region_alloc().free(reinterpret_cast<void *>(base));
 }
 
 
-Io_mem_session_component::Map_local_result Io_mem_session_component::_map_local(addr_t const base,
-                                                                                size_t const size)
+addr_t Io_mem_session_component::_map_local(addr_t base, size_t size)
 {
 	/* align large I/O dataspaces on a super-page boundary within core */
 	size_t alignment = (size >= get_super_page_size()) ? get_super_page_size_log2()
 	                                                   : get_page_size_log2();
 
-	/* find appropriate region and map it locally */
-	return platform().region_alloc().alloc_aligned(size, (unsigned)alignment).convert<Map_local_result>(
+	/* find appropriate region for mapping */
+	return platform().region_alloc().alloc_aligned(size, (unsigned)alignment).convert<addr_t>(
 
 		[&] (void *local_base) {
 			if (!map_local_io(base, (addr_t)local_base, size >> get_page_size_log2())) {
-				error("map_local_io failed ", Hex_range(base, size));
+				error("map_local_io failed");
 				platform().region_alloc().free(local_base, base);
-				return Map_local_result();
+				return 0UL;
 			}
-			return Map_local_result { .core_local_addr = addr_t(local_base),
-			                          .success         = true };
+			return (addr_t)local_base;
 		},
 
 		[&] (Range_allocator::Alloc_error) {
 			error("allocation of virtual memory for local I/O mapping failed");
-			return Map_local_result(); });
+			return 0UL; });
 }

repos/base-foc/src/core/ipc_pager.cc

@@ -12,6 +12,7 @@
  */
 
 /* Genode includes */
+#include <base/log.h>
 #include <base/thread.h>
 
 /* core includes */
@@ -24,7 +25,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 using namespace Foc;
 
 

repos/base-foc/src/core/irq_session_component.cc

@@ -14,6 +14,7 @@
  */
 
 /* Genode includes */
+#include <base/log.h>
 #include <util/arg_string.h>
 #include <util/bit_array.h>
 
@@ -27,15 +28,15 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-namespace Core { class Interrupt_handler; }
+namespace Genode { class Interrupt_handler; }
 
-using namespace Core;
+using namespace Genode;
 
 
 /**
  * Dispatches interrupts from kernel
  */
-class Core::Interrupt_handler : public Thread
+class Genode::Interrupt_handler : public Thread
 {
 	private:
 
@@ -52,7 +53,7 @@ class Core::Interrupt_handler : public Thread
 		static Foc::l4_cap_idx_t handler_cap()
 		{
 			static Interrupt_handler handler;
-			return handler.cap().data()->kcap();
+			return handler._thread_cap.data()->kcap();
 		}
 
 };
@@ -61,7 +62,7 @@ class Core::Interrupt_handler : public Thread
 enum { MAX_MSIS = 256 };
 
 
-struct Msi_allocator : Bit_array<MAX_MSIS>
+static struct Msi_allocator : Bit_array<MAX_MSIS>
 {
 	Msi_allocator()
 	{
@@ -78,14 +79,7 @@ struct Msi_allocator : Bit_array<MAX_MSIS>
 				set(info.nr_msis, MAX_MSIS - info.nr_msis);
 	}
 
-};
-
-
-static Msi_allocator & msi_alloc()
-{
-	static Msi_allocator instance;
-	return instance;
-}
+} msi_alloc;
 
 
 bool Irq_object::associate(unsigned irq, bool msi,
@@ -193,15 +187,14 @@ Irq_session_component::Irq_session_component(Range_allocator &irq_alloc,
 	_irq_number((unsigned)Arg_string::find_arg(args, "irq_number").long_value(-1)),
 	_irq_alloc(irq_alloc), _irq_object()
 {
-	Irq_args const irq_args(args);
-	bool msi { irq_args.type() != TYPE_LEGACY };
+	long const msi = Arg_string::find_arg(args, "device_config_phys").long_value(0);
 
 	if (msi) {
-		if (msi_alloc().get(_irq_number, 1)) {
+		if (msi_alloc.get(_irq_number, 1)) {
 			error("unavailable MSI ", _irq_number, " requested");
 			throw Service_denied();
 		}
-		msi_alloc().set(_irq_number, 1);
+		msi_alloc.set(_irq_number, 1);
 	} else {
 		if (irq_alloc.alloc_addr(1, _irq_number).failed()) {
 			error("unavailable IRQ ", _irq_number, " requested");
@@ -209,13 +202,15 @@ Irq_session_component::Irq_session_component(Range_allocator &irq_alloc,
 		}
 	}
 
+	Irq_args const irq_args(args);
+
 	if (_irq_object.associate(_irq_number, msi, irq_args.trigger(),
 	                          irq_args.polarity()))
 		return;
 
 	/* cleanup */
 	if (msi)
-		msi_alloc().clear(_irq_number, 1);
+		msi_alloc.clear(_irq_number, 1);
 	else {
 		addr_t const free_irq = _irq_number;
 		_irq_alloc.free((void *)free_irq);
@@ -230,7 +225,7 @@ Irq_session_component::~Irq_session_component()
 		return;
 
 	if (_irq_object.msi_address()) {
-		msi_alloc().clear(_irq_number, 1);
+		msi_alloc.clear(_irq_number, 1);
 	} else {
 		addr_t const free_irq = _irq_number;
 		_irq_alloc.free((void *)free_irq);
@@ -244,7 +239,7 @@ void Irq_session_component::ack_irq()
 }
 
 
-void Irq_session_component::sigh(Signal_context_capability cap)
+void Irq_session_component::sigh(Genode::Signal_context_capability cap)
 {
 	_irq_object.sigh(cap);
 }
@@ -256,7 +251,7 @@ Irq_session::Info Irq_session_component::info()
 		return { .type = Info::Type::INVALID, .address = 0, .value = 0 };
 
 	return {
-		.type    = Irq_session::Info::Type::MSI,
+		.type    = Genode::Irq_session::Info::Type::MSI,
 		.address = (addr_t)_irq_object.msi_address(),
 		.value   = _irq_object.msi_value()
 	};

repos/base-foc/src/core/native_cpu_component.cc

@@ -11,6 +11,9 @@
  * under the terms of the GNU Affero General Public License version 3.
  */
 
+/* Genode includes */
+#include <base/log.h>
+
 /* core includes */
 #include <native_cpu_component.h>
 #include <cpu_session_component.h>
@@ -19,7 +22,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 Native_capability Native_cpu_component::native_cap(Thread_capability cap)
@@ -35,7 +38,7 @@ Native_capability Native_cpu_component::native_cap(Thread_capability cap)
 Foc_thread_state Native_cpu_component::thread_state(Thread_capability cap)
 {
 	auto lambda = [&] (Cpu_thread_component *thread) {
-		return (!thread) ? Foc_thread_state { }
+		return (!thread) ? Foc_thread_state()
 		                 : thread->platform_thread().state(); };
 
 	return _thread_ep.apply(cap, lambda);

repos/base-foc/src/core/pager.cc

@@ -13,6 +13,10 @@
  * under the terms of the GNU Affero General Public License version 3.
  */
 
+/* Genode includes */
+#include <base/env.h>
+#include <base/log.h>
+
 /* core includes */
 #include <pager.h>
 
@@ -22,7 +26,7 @@
 /* Fiasco.OC includes */
 #include <foc/syscall.h>
 
-using namespace Core;
+using namespace Genode;
 
 
 void Pager_entrypoint::entry()
@@ -60,7 +64,12 @@ void Pager_entrypoint::entry()
 					}
 
 					/* handle request */
-					if (obj->pager(_pager) == Pager_object::Pager_result::CONTINUE) {
+					if (obj->pager(_pager)) {
+						/* could not resolv - leave thread in pagefault */
+						warning("page-fault, ", *obj,
+						        " ip=", Hex(_pager.fault_ip()),
+						        " pf-addr=", Hex(_pager.fault_addr()));
+					} else {
 						_pager.set_reply_dst(Native_thread(obj->badge()));
 						reply_pending = true;
 						return;
@@ -140,19 +149,12 @@ Pager_capability Pager_entrypoint::manage(Pager_object &obj)
 {
 	using namespace Foc;
 
-	return _thread_cap.convert<Pager_capability>(
-		[&] (Thread_capability thread_cap) {
-			Native_capability cap(_cap_factory.alloc(thread_cap));
+	Native_capability cap(_cap_factory.alloc(Thread::_thread_cap));
 
-			/* add server object to object pool */
-			obj.cap(cap);
-			insert(&obj);
+	/* add server object to object pool */
+	obj.cap(cap);
+	insert(&obj);
 
-			/* return capability that uses the object id as badge */
-			return reinterpret_cap_cast<Pager_object>(cap);
-		},
-		[&] (Cpu_session::Create_thread_error) { return Pager_capability(); });
+	/* return capability that uses the object id as badge */
+	return reinterpret_cap_cast<Pager_object>(cap);
 }
-
-
-void Core::init_page_fault_handling(Rpc_entrypoint &) { }