=============================================== Release notes for the Genode OS Framework 16.05 =============================================== Genode Labs After ten years of developing and refining the Genode OS Framework and conducting countless experiments, it is time to condense the gathered body of experience into a fundamentally revised API. Version 16.05 marks the most profound API change in the project's history. The underlying motivation is to reduce complexity while preserving the flexibility of the framework. With a narrow and orthogonal API, components become easier to develop, to evaluate, and to maintain. The second motivation is our aspiration to ultimately attain a stable binary interface that works across different kernels. The new API is a significant step in this direction. Section [The great API renovation] presents the rationale behind these changes, and outlines the steps for migrating to the new API. It is complemented by technical details given in Section [Base framework] and a comprehensive documentation update (Section [New revision of the Genode Foundations book]). The second focus of the current release is the update of Genode's arsenal of device drivers, in particular the driver stacks ported from Linux. Those drivers comprise the Intel wireless stack, the Intel graphics driver, the Linux TCP/IP stack, and the Linux USB stack. Genode scenarios can now take advantage of the same drivers as modern Linux distributions based on the Linux kernel version 4.4.3. Furthermore, the audio driver ported from OpenBSD received an update. Section [Device drivers] describes this line of work in detail. The device-driver topic is nicely complemented with a greatly improved ACPI support presented in Section [Enhanced ACPI support]. With respect to the framework's feature set, version 16.05 introduces the ability to use the Rust programming language for Genode components (Section [New support for the Rust programming language]), and allows the GNU debugger to be used on top of 64-bit NOVA (Section [Enhanced GDB support on NOVA]). According to the [https://genode.org/about/road-map - road map], we originally planned a few more functional additions that did not make it into the release. Even through the work on the package-management topic [https://github.com/nfeske/genode-pkg - progresses], we are still at an experimental stage. We decided to defer the work on the NAT component and instead focused on improvements of the base-hw kernel (Section [Execution on bare hardware (base-hw)]) that are highly anticipated by the developers of the Muen separation kernel. Speaking of [https://muen.sk - Muen], the support for running Genode on this kernel has reached the state where Virtualbox can be executed inside a Muen partition. However, we decided to not rush the integration of this feature into Genode's mainline. Right now, it still resides on a topic branch. If you are eager to try it out right now, please get in touch via the [https://genode.org/community/mailing-lists - mailing list]. The great API renovation ######################## Genode's base API evolved over the years. When we started in 2006, our mindset was very much influenced by L4, which regarded synchronous IPC as the only mechanism required. We used to implement components ("servers") in a procedural programming style with a fully synchronous control flow within and across components (IPC). We eventually realized that the restriction to synchronous IPC was misguided (see Section 3.6.2. "Asynchronous notifications" in [https://genode.org/documentation/genode-foundations-16-05.pdf - the Genode Foundations book] for a detailed discussion of the problems). When we started to embrace the use of asynchronous notifications and to disregard blocking RPC between components, we found ourselves designing components as state machines rather than procedural programs. To promote this programming style, we introduced the so-called server API (_os/server.h_). See [https://github.com/genodelabs/genode/blob/master/repos/os/src/server/nic_loopback/main.cc - NIC loopback server] for a canonical example of such a component. We found that this new style greatly increased the robustness and flexibility of the components. In particular, it completely alleviates race conditions, which constantly troubled us in the past. Now, following the new paradigm, we may end up in a deadlock, but such a situation is easy to debug compared to sporadic race conditions. Over the past two years, we have redesigned all Genode session interfaces to avoid blocking RPC. The only remains are the parent and root interfaces, which we still need to address. Still, the Genode API retained compatibility to the old (= wrong) style of developing components. We take the current release as an opportunity to finally clean the API from our past mistakes. High-level overview of the changes ================================== Removal of side effects ----------------------- Up to now, most components rely on the globally available 'Genode::env()' singleton object for interacting with its environment. When calling a function or method, one never knows for sure if the called code interacts with the 'env'. E.g., we can simply create an instance of 'Timer::Connection' without any arguments. Under the hood, the 'Connection' object accesses the 'env' to open a timer session at the parent. In the spirit of capability-based security, we should shun the reliance on side effects like the global 'env'. Instead, we should pass all materials that are needed by the called code explicitly to the called code (e.g., by passing a reference to a 'Parent &' as argument). This way, someone inspecting the calling code can immediately see the possible reach of the called code. Another prominent example is the latent use of 'env()->heap()', which allows any code to arbitrary consume memory. Instead, we should better pass an 'Allocator &' to the called code. This way, we re-enforce that library code stays clean from the policy where memory is allocated from. If no 'Allocator &' is passed, we know that no dynamic memory allocation can be performed. If an 'Allocator &' is required, the called code needs to explain (in the form of its documentation) why the allocator is actually needed. Moreover, by passing an 'Allocator_guard', the calling code can impose a limit of the memory consumption on the called code. Component API ------------- Traditionally, components started their execution at a 'main' function because, well, this is how it's supposed to be, right? The program exits as soon as main returns. With the introduction of the server API mentioned above, we explored a different approach: The execution of a component starts at a 'construct' function that takes a form of the Genode environment as argument. The function is expected to initialize the component. Upon completion of the initialization, the function returns. At this point, the component becomes ready to respond to incoming RPC requests or signals. Each time such a request/signal comes in, a handler is executed. The handler applies the component-internal state changes and returns immediately. No blocking call is performed. We have essentially a state machine. Over the past two years, we have applied this new approach to all new components - to a great success. So it is time to promote this API to become Genode's base API. The major benefits are: * Servers become easier to develop as the API is much simpler. Previously, a server had to manually create a CAP connection and an RPC entrypoint. Now, each component has a ready-to-use entrypoint. * Signals and RPC requests are handled in the context of the same thread, which alleviates the need for locking as long as the component is single threaded, which is actually the case for most components. * The notions of 'Thread', 'Signal_receiver', 'Rpc_entrypoint' are no longer needed by the developer of a component. There is simply an 'Entrypoint', which is able to handle both RPC requests and signals. Shunning pointers ----------------- The Genode API has still a lot of places where pointers are taken as arguments or exposed from objects. We didn't know better when we started with Genode. Now we do. With the current release, we streamline the base API in this respect. Just as one simple example, the 'Heap' used to take an RM-session pointer and an RAM-session pointer as arguments. These should be references. Pointers should be used only in situations where a nullptr is a reasonable argument, or when dealing with string literals as 'char const *'. We are not there yet -------------------- Whereas we find designing an API that successfully strikes the balance between the lowest possible API complexity and highest possible flexibility extremely challenging, we find ourselves even more challenged with the execution of the transition from one API to another. The order of steps must be planned carefully and interim solutions must be designed as migration paths. We hope that the current release does not induce too much pain for the users of the framework. Wherever we found a way to smoothen the migration path, we took it. But there are a few disruptive changes that are explained in detail in Section [Base framework]. There are still a few loose ends that we will address in the subsequent release, in particular the redesign of the parent interface to become completely asynchronous. New revision of the Genode Foundations book =========================================== The profound changes of the Genode API prompted us to update the Genode Foundations book accordingly. Whereas the principle architecture remained unchanged, many details needed an adjustment. The changes between the last year's edition and the current revision are: :
:

:

: : : :
:

* Consolidation and interface changes of core services (CAP, SIGNAL, RM, CPU, PD), * Architectural changes related to the management of virtual-memory regions (region maps), * Updated functional specification matching the new API (e.g., 'Entrypoint', 'Env', 'Component', 'Thread', log API, IPC), * Updated NOVA modifications and limitations (kernel-memory quotas, remote unmap, 64-bit guests, write-combining), * Label-dependent session routing / policy selection :
To see the changes in detail, please refer to the book's [https://github.com/nfeske/genode-manual/commits/master - revision history]. As another useful resource to get acquainted with the new API, please also consider the [https://genode.org/documentation/developer-resources/client_server_tutorial - updated client-server tutorial]. API migration guide =================== In the current release we promote the former "server API" to the general "component API", which should solely be used for new components. The old API is now considered as deprecated. This short guide provides the list of steps one has to take to adapt an existing server-API-style component to the new API. The steps are as follows: # Replace include directives The 'Server' namespace is superseded by the 'Component' namespace and the 'Entrypoint' class has moved to the Genode namespace. Therefore, instead of including the _os/server.h_ header, the _base/component.h_ header must be included. # Replace server definition Where the old API used the Server hook functions !char const *Server::name() { return "server_ep"; } !size_t Server::stack_size() { return 8*1024*sizeof(long); } !void Server::construct(Entrypoint &ep) { static Main main(ep); } the new API uses the Component hook functions !size_t Component::stack_size() { return 8*1024*sizeof(long); } !void Component::construct(Genode::Env &env) { static Main main(env); } Note that the 'name()' function ceased to exist. # Use 'Env' reference Whereas the old API passes a reference to an 'Entrypoint', the new API passes a reference of the 'Genode::Env' to the component's 'construct' function. The initial entrypoint of the component can be accessed through the 'Env' reference by calling the 'ep()' method. As intermediate step while doing the migration work, it is sufficient to call this method in the 'construct()' method, e.g.: !void Component::construct(Genode::Env &env) { static Main main(env.ep()); } # Replace 'Signal_rpc_member' The 'Signal_rpc_member' class is considered deprecated and superseded by the 'Signal_handler' class (see _base/signal.h_). Note that the actual signal-handling method as passed to a 'Signal_handler' has no argument, as opposed to the old API where the handler was called with a counter value. # Replace global 'Genode::env()' accessor The most cutting change is the discontinuation of the global 'Genode::env()' accessor function. Typically, this accessor was used throughout a component to access its environment, e.g. use 'Genode::env()->heap()' as allocator or 'Genode::env()->rm_session()->attach()' to attach a dataspace. Since a component starts its life now at the execution of the 'construct' function, the component has to pass a reference to its 'Env' interface or rather a reference to the needed part of the 'Env' interface on. This explicit way of handling access to the component's environment will require a restructuring of the component. It is good practice to focus on the need at hand rather than to always pass the 'Env' reference on. On that account, it is important to note that the 'Rm_session' is no longer accessible and its place is taken by the 'Region_map'. Where one would have called 'env()->rm_session()->attach' to attach a given dataspace, 'env.rm().attach' has now to be used. Furthermore, the global heap allocator object was removed. Components that want to use a heap like allocator have to create such an allocator manually: !Genode::Heap heap { &env.ram(), &env.rm() }; # Use new log facilities Instead of relying on the old print macros (PDBG, PERR, PINF, PLOG, PWRN) and thereby 'Genode::printf()', a component should use the new 'Log' class to produce diagnostic LOG output. There are a few convenient template functions, namely 'Genode::error()', 'Genode::log()' and 'Genode::warning()' that can be used. Note that these functions do not use a format string to print various different data types but just a list of arguments, e.g.: !int const i = 42; !char const * str = "world"; !Genode::log("Hello ", str, "! ", i); produces 'Hello world! 42'. Note that certain data types, e.g. 'enum' and 'char', might have to be casted, e.g.: !enum { FOO, BAR }; !Genode::log("enum: ", (int)FOO, " ", (int)BAR); Base framework ############## New component API ================= Each component is a composition of a protection domain (PD session), a memory budget (RAM session), and a CPU session, from which the initial thread is created. These sessions form the _environment_ of the component, which is represented by the 'Env' interface class (_base/env.h_). The environment is provided to the component as argument to the 'Component::construct' (_base/component.h_) function. :deprecated global 'env()' accessor function: During the migration phase to the new API, the 'Genode::env()' is still available. But it will ultimately vanish from the API. Each component is equipped with an initial 'Entrypoint' (_base/entrypoint.h_) that is accessible via 'Env::ep()'. Each entrypoint is able to respond to both RPC requests and signals. The 'Component::construct' function is executed in the context of the entrypoint. None of the entrypoint's RPC objects or signal handlers will be called before returning from the 'Component::construct' function. :deprecated 'Rpc_entrypoint': The 'Rpc_entrypoint' should no longer be used by components directly. Internally, the 'Entrypoint' is still using an 'Rpc_entrypoint' as underlying mechanism for now, but the 'Rpc_entrypoint' will eventually be removed from the API. :deprecated _os/signal_rpc_dispatcher.h_: The former 'Signal_rpc_member' is superseded by the new 'Signal_handler' (_base/signal.h_). Signal-handling methods receive no longer a signal counter value as arguments as there haven't been any convincing use cases for this feature. In the contrary, it actually led to wrong design choices in the past where the rate of signals carried information (such as the progress of time) that should better be obtained via an explicit RPC call. :deprecated connection constructors without 'Env' argument: To eliminate the reliance on the deprecated global 'env()', all connection objects have to take a reference to the component's environment as argument. The original constructors are marked as deprecated. Once we have completely abolished the use of the global 'env()', we will remove them. Consolidation of core's SIGNAL, CAP, RM, and PD services ======================================================== With the new API, each component implicitly requires a session to core's CAP service (to be able to handle RPC requests by the entrypoint) and a session to the SIGNAL service (to dispatch signals by the entrypoint). Therefore, the separation of these services serves no purpose any longer. To simplify the API, the former SIGNAL, CAP, RM, and PD services are now integrated into the PD service. This change has several benefits: * It reduces the API complexity, * It reduces the component-startup costs because only one session must be created instead of four. * It reduces policy with respect to the dimensioning of the various session quotas. In order to unify the API across all different base platforms, the PD session interface contains no kernel-specific parts any longer. There is now a dedicated sub interface called 'Native_pd' that accommodates such needs. A capability to this kernel-specific interface can by requested via the 'Pd_session::native_pd' accessor method. The kernel-specific interfaces are named 'Nova_native_pd', 'Foc_native_pd', and 'Linux_native_pd'. :deprecated _cap_session_: With the integration of the CAP service into the PD service, the CAP session interface ceased to exist. However, there are still old-style components that manually create a 'Cap_connection' to be passed as argument to an 'Rpc_entrypoint'. To avoid breaking those components, we keep a pseudo 'Cap_connection' around. But the implementation does not actually create a session but merely returns the PD session interface of the component, which coincidentally matches the argument type of the 'Rpc_entrypoint'. :new _region maps_ replace former RM sessions: The functionality of the former RM sessions has moved to the region-map interface, which is an RPC interface but not a session. Each PD session contains 3 region maps, one for the entire virtual address space, one for the stack area (formerly called thread-context area), and one for the linker area. The new RM service is merely responsible for the provisioning of managed dataspaces but is no longer used by regular components. As a minor refinement, the 'Fault_type' enum values are now part of the 'Region_map::State' struct. New log-output facilities ========================= Throughout Genode, we used to rely on C-style format strings for the output of diagnostic information and for the assembly of strings. There are many shortcomings of this approach such as the limitation of the printable types to the built-in format-string specifiers, the lack of type safety, and the mismatch between the implementation and the intuitive expectations by the API users (who usually expect POSIX compliance). With the current release, we introduce the new log-output facility _base/log.h_ that will ultimately replace the original set of convenience macros PDBG, PWRN, PERR, PINF by C++ function templates using variadic template arguments. The function templates are plainly called 'log', 'error', and 'warning' residing in the 'Genode::' namespace. The replacement for 'PDBG' must be a macro in order to encode the calling function name into the string. As of now, this functionality is not yet covered by _base/log.h_. The header _base/output.h_ contains the mechanics for the extraction of a textual representation from values and object instances. It provides the abstract 'Output' interface to be implemented by a consumer of text. Functions for generating output for different types are named 'print' and take an 'Output &' as first argument. The second argument is a 'const &' to the value to print. Overloads of the 'print' function for commonly used basic types are readily provided. The following example illustrates how 'print' functions for custom types may be used. ! enum Test_state { STATE_0, STATE_1 }; ! static void print(Genode::Output &output, Test_state const &state) ! { ! switch (state) { ! case STATE_0: output.out_string("STATE_0"); break; ! case STATE_1: output.out_string("STATE_1"); break; ! } ! } ! ... ! Test_state state; ! state = STATE_0; Genode::log("test: ", state, " = ", (int)state); ! state = STATE_1; Genode::log("test: ", state, " = ", (int)state); Furthermore, there is a function template that is used if none of the type-specific overloads match. This function template expects the argument to be an object with a 'print' method. In contrast to a plain 'print' function overload, such a method is able to incorporate private object state into the output. The component's execution environment provides an implementation of the 'Output' interface that targets a LOG session. This output back end is offered to the component in the form of the 'log', 'warning', and 'error' functions that accept an arbitrary number of arguments that are printed in a concatenated fashion. Each messages is implicitly finalized with a newline character. :deprecated _base/printf.h_, _base/console.h_, and _base/snprintf.h_: The goal of the new output facilities is the complete removal of format strings from the Genode API. Hence, the listed headers should be avoided. XML processing ============== Since the first version, Genode's init component relied on configurations in an XML-like syntax. For a long time, however, we remained hesitant to make the base system (core and the base API) inherently dependent on XML. For the most part, this hesitance was founded on our observation that XML tends to be disliked in systems-programmers circles. However, over the years, XML organically became the predominant syntax for component configuration as well as for the propagation of state between components. Whereas the syntactical merits of XML are highly subjective and perhaps debatable, the beauty of using XML within Genode lies in its consistent application. For example, it allows us to naturally embed a component configuration in another component's configuration without even thinking about it. Much of Genode's flexibility that we enjoy today can be attributed to this coherency. Granted, this argument would apply just as well to alternatives such as JSON or s-expressions. But we have to take one choice and stick to it. Whereas we found that XML satisfies our needs and actually never stands in the way, the impact on the code complexity is negligibly. Our XML parsing and generating utilities are in the order of 700 lines of code. With this perspective, we take now the deliberate decision to make XML mandatory for even the lowest-level parts of the framework. For example, even the dynamic linker obtains the policy for diagnostic output from an XML-formatted configuration. Consequently, we moved the XML utilities to _base/include/util/_. To ease the use of the XML parsing utilities, we also added the accessors 'Xml_node::type' and 'Xml_attribute::name' that return 'Genode::String' objects. :changed constructor of 'Reporter': One prominent use of XML is the reporting of state information from components to a report service. Most components facilitate the 'Genode::Reporter' for this job. Originally, the report name was used implicitly as the top-level XML node type of the report. This is inconvenient if one component needs to generate various XML reports under various names (e.g., to steer consumers/clients slightly differently) but with the same XML node tree structure. To accommodate those needs, the 'Reporter' now takes the XML node type and the report label as two distinct arguments. Dataspace helpers ================= The use of dataspaces, e.g., for setting up shared memory between components, involves typical sequences of operations, e.g., for attaching the dataspace to the local address space. The 'Attached_*_dataspace' utilities located at _os/include/os/_ take care of these technicalities. With the current release, we promote them to become part of the base API. Thereby, we can leverage those utilities even for the lowest-level components and internally within the framework. On that account, the corresponding header files were moved to _base/include/base/_. :changed constructors of 'Attached_*_dataspace' utilities: Originally, the dataspace utilities relied on side effects via the 'Genode::env()' accessor. To break away from this bad practice, the new versions have constructors that take all needed resources as explicit arguments. The original constructors are scheduled for removal. The most common use case of 'Attached_rom_dataspace' is the consumption of XML-formatted data. To accommodate this common pattern, we equipped the 'Attached_rom_dataspace' with an accessor plainly named 'xml'. It always returns a valid 'Xml_node' even in the event where the dataspace is invalid or contains no XML. In such cases, the returned XML node is ''. This way, we spare the caller the handling of exceptions that may occur during XML parsing. With this change in place, a configuration attribute can be obtained as follows: !Genode::Attached_rom_dataspace config(env, "config"); !... !bool const verbose = config.xml().attribute_value("verbose", false); :deprecated _os/config.h_: Since it has become so easy to consume XML from ROM sessions, the role of the former 'Genode::config()' interface has become largely obsolete. In line with our goal to eliminate global side effects, the _os/config.h_ has become deprecated. Thread API and CPU-session interface ==================================== The thread API and the CPU-session interface underwent a major revision. CPU session interface --------------------- :Assigning threads to a PD at their creation time: We replaced the former 'Pd_session::bind_thread' method by a PD-capability argument of the 'Cpu_session::create_thread' method, and removed the ancient thread-start protocol via 'Rm_session::add_client' and 'Cpu_session::set_pager'. Threads are now bound to PDs at their creation time and implicitly paged according to the address space of the PD. :New 'Cpu_session::Weight' type: The new type replaces a formerly used plain integer value to prevent the accidental mix-up of arguments. The enum definition of 'Cpu_session::DEFAULT_WEIGHT' moved to 'Cpu_session::Weight::DEFAULT_WEIGHT'. :Separation of platform-specific operations from generic CPU session: The CPU session interface has been unified across all platforms. The former differences were moved to respective "native-CPU" interfaces analogously to how the 'Native_pd' interface is separated from the 'Pd_session' interface. :Separation of thread operations from CPU session: The former CPU-session interface contained a number of operations that took a thread capability as first argument. Those thread-manipulation operations are now accessible as RPC functions on the thread capability directly. A noteworthy semantic change is the meaning of the former 'exception_handler' RPC function, which used to define both the default exception handler or a thread-specific signal handler. Now, the 'Cpu_session::exception_sigh' function defines the CPU-session-wide default handler whereas the 'Cpu_thread::exception_sigh' function defines the thread-specific one. Thread API ---------- Most regular components no longer need to use the thread API directly. Instead, the 'Entrypoint' (which is a thread) should be used whenever possible. :removed details from _base/thread.h_: We moved the details about the stack allocation and organization from the public API to framework-internal headers and replaced the notion of "thread contexts" by "stacks" as this term is more intuitive. :renamed and removed classes, new constructors: The former 'Thread<>' class template has been renamed to 'Thread_deprecated'. Threads with the stack supplied as template argument should no longer be used. The stack size should always be passed as constructor argument. The former 'Thread_base' class is now called 'Thread'. The new Thread constructor takes an 'Env &' as first argument, followed by the thread's parameters such as the affinity and scheduling weight. The original constructors are now marked as deprecated. For the common use case where the default 'Weight' and 'Affinity' are used, a shortcut is provided. In the long term, those two constructors should be the only ones to remain. A new 'name()' accessor returns the thread's name as 'Name' object as centrally defined via 'Cpu_session::Name'. It is meant to replace the old-fashioned 'name' method that takes a buffer and size as arguments. Child management ================ The 'Child' class has been adapted to the changed core services and partially redesigned to enable the implementation of single-threaded runtime environments that virtualize the CPU, PD, and RAM services. It thereby has become free from side effects. I.e., instead of implicitly using 'Genode::env()->rm_session()', it takes the reference to the local region map as argument. Also, the handling of the dynamic linker via global variables is gone. Now, the linker binary must be provided as constructor argument. Stylistic changes ================= :'Heap', 'Sliced_heap', 'Root_component': We added new constructors to these classes that take references, not pointers, as arguments. The old constructors will be removed with the next release. :Naming of boolean getter methods: We already follow a convention about the naming of accessor methods (not using any get_ or set_ prefixes). However, we sometimes used an "is_" prefix for getter functions of boolean values, but not always. Examples are 'Capability::valid()' and 'Weak_ptr::is_valid()'. In the name of the principle of least surprise, we introduced the convention to not use an "is_" prefix for such methods. We adjusted all occurrences within the Genode code base accordingly. To maintain API compatibility during the transitional phase, we also keep the original methods until the next release. :Alleviating the need for manually constructed type lists: The 'GENODE_RPC_INTERFACE' macro of the RPC framework had a limitation with respect to the number of RPC functions per RPC interface. As a workaround for this limitation, large session interfaces had to manually define the type list of RPC functions out of nested type tuples. With the current release, we removed this limitation. Removed and to-be-removed APIs ============================== :removed _base/crt0.h_ and _base/elf.h_: Those headers are internally needed by the framework but contain no actual value at the API level. Therefore we removed them from the public API. :removed _base/process.h_: The 'Process' class encapsulated the platform-specific steps to start a Genode component from a given ELF file. The original intention of placing this low-level functionality into a dedicated class was to allow for different flavours of child-management policies. In practice, however, the 'Process' remained solely being used by the 'Genode::Child'. Since the core-interface changes of Section [Consolidation of core's SIGNAL, CAP, RM, and PD services] required us to rewrite the component-creation code anyway and we aspire to narrow the API, we took the chance to make 'Process' private to the 'Child'. Thereby, the rather ambiguous term "process", which we avoid in the context of Genode by speaking of "components" instead, is eliminated from the public API. :discourage use of _util/arg_string.h_: The 'Arg_string' utilities are used to generate and parse session-argument strings. However, to make Genode more coherent and session arguments more flexible and robust, we plan to replace the current argument-string syntax with XML, eventually removing the argument-string support. Hence, we discourage the use of 'util/arg_string.h'. :discourage use of _base/signal.h_: The introduction of the new 'Entrypoint' eliminates the need to manually create and use 'Signal_receiver' objects. Right now, we still rely on the original signal API as backend of the 'Entrypoint' but we will eventually remove the current notion of signal receivers. The narrower semantics of the 'Entrypoint' will then allow for performance optimizations that are not possible with the traditional signal receivers. Therefore, we discourage the direct use of 'Signal_receiver'. Low-level OS infrastructure ########################### Enhanced GDB support on NOVA ============================ During the practical work with the GDB monitor (our Genode port of the GNU 'gdbserver' application) and our nightly automated execution of the 'gdb_monitor.run' test, it turned out that there are still situations that the GDB monitor cannot handle correctly. Since the error symptoms often occured sporadically and it was not obvious whether the cause of the error was located in the Genode-specific adaptations of the gdbserver code or in the platform- specific functionality of the Genode base system. As a first step to improve the stability of the debugger we tried to remove existing Genode-specific code from the gdbserver codebase and emulated the Linux-specific C interface instead. This involved a GDB-monitor-local implementation of the 'waitpid()' which is documented relatively well. In the case of an error, there would be a better chance of comparing the GDB monitor- internal execution sequence with a corresponding test case on the Linux version of gdbserver. The emulation of this interface is not trivial, though, because the behavior of the Linux kernel often differs from the behavior of the Genode base components. For example, when debugging a Linux program, a new thread created by the debug target gets stopped automatically by the Linux kernel, the 'waitpid()' function then reports a SIGSTOP signal for the new thread and a SIGTRAP signal for the creating thread to the gdbserver. This behavior does not match at all with the design of the Genode base system. Therefore, we emulate it in the GDB monitor with the help of a software breakpoint on the first instruction of the new thread and an artificial creation of the corresponding SIGSTOP and SIGTRAP signal reports. While implementing this mechanism on the NOVA base platform, we encountered several NOVA-specific corner cases. On NOVA, an RPC server is implemented by a so-called "local ECs" - a NOVA thread, which only responds to IPC and has no execution time of its own. When creating a local EC, the initial instruction pointer as passed to the 'Cpu_thread::start' function is always 0. The real instruction pointer is defined by a so-called NOVA portal used for calling the local EC. To determine the correct start address of the thread - as needed by GDB monitor to set the initial breakpoint - changes if the NOVA base system were necessary. The next show stopper was an attempt by GDB monitor to pause a thread of the debug target could block for quite some time if the particular thread was currently blocking in a NOVA syscall. We also found that GDB monitor could block for quite some time when trying to pause a debug target. This behavior was caused by the targeted thread being in a system call, and therefore within the NOVA hypervisor, by the time of pausing. In that case, the 'Cpu_thread::pause' call returned only after the particular thread got executed in userland again, because only then the current register state of the thread can be transferred into userland for retrieval by GDB. We solved this problem by extending the NOVA kernel, which makes it possible to obtain the current register state of a to-be-paused thread immediately whenever possible. Furthermore, the NOVA-specific changes for GDB enable the debugger to modify register values and to debug 64-bit applications. As reference, the 'ports/run/gdb_monitor.run' script demonstrates and tests a selection of the features supported by GDB on Genode. New support for the Rust programming language ============================================= [https://www.rust-lang.org/ - Rust] is a systems programming language that currently gains a lot of popularity. It eliminates entire classes of bugs by enforcing memory safety. Unlike languages that rely on a garbage-collecting runtime, compiled Rust programs are able to run on bare-metal hardware. This makes Rust an attractive language for low-level system components. The current Genode release introduces basic support for executing Rust programs as Genode components. This support includes the build-system integration, the configuration of the LLVM-based Rust compiler, and the port of the low-level language runtime. A simple example is provided via the _libports/run/rust.run_ script and the accompanied code at _libports/src/test/rust/_. The example runs on the x86 (32 and 64 bit) and ARM architectures. The port uses the nightly-built rust tool chain from 2016-03-03, so the nightly compiler from that day is guaranteed to work. It can be downloaded with via the following command: ! curl -sSf https://static.rust-lang.org/rustup.sh |\ ! sh -s -- --channel=nightly --date=2016-03-03 Alternatively, it can be [https://static.rust-lang.org/dist/2016-03-03/index.html - manually downloaded]. Thanks to Waylon Cude for bringing Rust to Genode! Dynamic linker ============== The dynamic linker will now check if the binary pointer is valid before attempting to lookup a symbol. Shared objects with unresolved symbols and missing dependencies, e.g., a library that references 'errno' but is not linked against libc, will now produce an error message when they are loaded by the dynamic linker instead of triggering an ominous page-fault. New component for writing ROM modules to files ============================================== The ROM-to-file component at _repos/os/src/app/rom_to_file_ requests a ROM session and writes the content of the ROM dataspace to a file of a file-system session. It is able to respond to configuration and ROM-module updates. The name of the ROM module must be specified via the 'rom' attribute of the component's '' node: ! See _run/rom_to_file.run_ for an example. Thanks to Johannes Schlatow for this contribution! C runtime ========= Sysctl ~~~~~~ The libc sysctl was replaced with an extensible implementation that reads values from the _/.sysctl_ directory when present. This interface is convergent with the _/proc/sys_ directory on Linux and allows sysctl values to be modified by the local component or by an external component through a common file system. libc_pipe plugin ~~~~~~~~~~~~~~~~ The new 'libc_pipe' plugin provides a more accurate implementation of pipes (using a ring buffer) and replaces the existing 'libc_lock_pipe' plugin. Device drivers ############## In this release, we updated several device drivers ported from foreign OSes. In addition, we consolidated all drivers in the _dde_linux_ repository by utilizing a new modular _lx_kit_ and made sure that each driver is using the same Linux version now. HDA audio driver update ======================= The audio driver was synced with version 5.9 of OpenBSD. In addition to updating the contrib sources, the driver now uses the new component API and reports the internal mixer state. Reporting of the mixer state is enabled by adding the 'report_mixer' attribute to the drivers configuration and setting its value to 'yes'. The following snippet illustrates the format of the report: ! ! ! ! ! ! ! The mixer state can expose other mixer fields as well, depending on the used hardware. The naming scheme of the attributes intentionally matches the naming scheme of OpenBSD's mixerctl(1) program. In return, 'mixer' nodes may be used to configure the audio driver by specifying it in the configuration, e.g.: ! ! ! will set the output volume to the highest possible value. Although it is now also possible to update the configuration at run time, this should be done with care. Updating the configuration while the driver is playing or recording may provoke audible artifacts. For now it is best to use the mixer component to regulate the volume rather than adjusting the audio driver directly. Linux kit ========= Over the years, the way we handled our DDEs has changed. By now it became clear that it is easier to manage ported drivers without having to rely a generic API like dde_kit. Using Genode primitives directly enabled us to specially tailor each DDE to the driver in question. That being said, when having four different drivers (intel_fb, lxip, usb and wifi) and each one with its own specially tailored DDE, the amount of redundant code became huge. We created the lx_kit that enables us to share code across the drivers to address this issue. Thereby we reduced the amount of redundant code. This modular lx_kit separates the required back-end functionality of the Linux emulation environment from the front end. Thereby each driver can reuse generic parts and supply more suitable implementations by itself. It is split into several layers whose structure is as follows: The first layer in _repos/dde_linux/src/include/lx_emul_ contains those header files that provide the structural definitions and function declarations of the Linux API, e.g. _errno.h_ provides all error code values. The second layer in _repos/dde_linux/src/include/lx_emul/impl_ contains the implementation of selected functions, e.g. _slab.h_ provides the implementation of 'kmalloc()'. The lx_kit back end API is the third layer and provides the _Lx::Malloc_ interface (_repos/dde_linux/src/include/lx_kit/malloc.h_), which is used to implement 'kmalloc()'. There are several generic implementations of the lx_kit interfaces that can be used by a driver. A driver typically includes a 'lx_emul/impl/xyz.h' header once directly in its lx_emul compilation unit. The lx_kit interface files are only included in those compilation units that use or implement the interface. If a driver wants to use a generic implementation, it must add the source file to its source file list. The generic implementations are located in _repos/dde_linux/src/lx_kit/_. The modular lx_kit still depends on the private _lx_emul.h_ header file that is tailored to each driver. Since the lx_kit already contains much of the declarations and definitions that were originally placed in these private header files, those files can now omit a large amount of code. Wifi driver update ================== The wifi_drv was updated to Linux version 4.4.3 and thereby adds support for Intel 8xxx wireless cards. In order to ease debugging, the driver now enables its debugging messages when the 'verbose' attribute in its '' node is set to 'yes'. USB driver update ================= The USB driver was updated to Linux version 4.4.3 and like the other drivers incorporates the modular lx_kit. The new driver exposed problems with the EHCI controller on older systems, namely the Thinkpad X201. Using the new USB driver on this machine would freeze the system when 'USB legacy Support' is enabled in the BIOS. The fix is to conduct a so-called USB hand-off that informs the BIOS that the OS wants to drive the USB host-controller and waits until the BIOS has acknowledged the request. Unfortunately, applying this quirk produces problems on certain xHCI host-controllers when using the IOMMU. In this case the driver tried to perform the hand-off request but got stuck while writing to the PCI config space. After about 20 seconds, we observed a DMA fault and the initialization of the USB driver went on. Presumably at this point the BIOS tries to access certain memory regions that - by now - are protected by the IOMMU. When using the IOMMU, we already take precautions, i.e., we look at the RMRR regions and instruct the kernel to configure the IOMMU for specific devices accordingly. We looked at the ACPI RMRR region of the USB on the machine in question and could confirm our suspicion: the registered USB RMRR region is indeed too small. For all we know, that sounds like a bug in BIOS or rather ACPI tables. To accommodate systems that nonetheless need the hand-off quirk and the user wants to use the IOMMU, we added the handling of a 'bios_handoff' attribute to the USB driver configuration. When set to 'no' the driver will not perform any hand-off request. The default setting is 'yes'. If you experience any issues with the new USB driver, disabling the hand-off is advised. While updating the driver, a regression on the Raspberry Pi was introduced. USB devices that use IRQ endpoints, e.g. USB HID devices, do not work reliably. This issue is still unresolved and dealing with it is postponed until after the release. Furthermore, the USB session used for implementing native USB device drivers propagates an EP stall error to the client and clears the stall condition by resetting the EP now. Intel graphics driver update ============================ The Intel graphics driver introduced in Genode release 15.11 was updated to Linux version 4.4.3. The most prominent, functional improvement is support for Intel Skylake graphics cards. Internally, we slimmed the code parts used from the Linux kernel by resigning the ancient framebuffer and framebuffer console layer. The new driver only uses the more modern DRM layer of the Linux kernel. As a side effect, all formerly available heuristics that were applied at initialization time or whenever a display got connected are not part of the driver anymore. Now, the driver only reports any state changes like additional available displays via its report session. On the other hand it always updates the graphics configuration whenever its config ROM module changes. To automatically control the graphics driver during display connection changes, an example component named intel_fb_controller is now available at _repos/dde_linux/src/test/framebuffer/intel_. This component reacts on report changes of the Intel graphics driver and configures it in a way that all available displays are showing one and the same framebuffer with their maximum resolution. Thereby displays with a minor resolution show the upper left corner of the whole framebuffer. Enhanced ACPI support ===================== Modern PCs provide an enormous number of ways to monitor and configure the system via the Advance Configuration and Power Interface (ACPI) Specification. Since version 12.02, we have already a basic ACPI driver in Genode, which is mainly used to look up low-level data via some clever pattern-matching heuristics. These information, like interrupt remapping, are sufficient to bootstrap and setup the Genode user-level part of the system. We wanted to go beyond this feature set and leverage further - dynamic - aspects of ACPI such as system state changes of batteries in notebooks or lid status. The [https://acpica.org - ACPI Component Architecture project ACPICA] develops and maintains an operating-system-independent reference implementation of ACPI, which can be used by operating systems like Genode to utilize the full functionality of modern PCs. So we took the reference implementation of ACPICA and ported it to Genode. The port itself was relative straight forward and really a pleasure. The interfaces and abstractions to the operating system are well chosen by the ACPICA project, clearly documented, and a porter is well guided by extensive explanatory documentation. The port is hosted in the libports repository as a standalone library without any additionally dependencies (beside Genode's base library). To utilize and experiment with the ported library, we started to develop a Genode application called app/acpica, which utilizes the library. We experimented and managed to enable the ACPI lid, ACPI embedded controller (e.g. Fn keys), ACPI AC adapter, ACPI smart battery subsystem, and ACPI fixed events, e.g., power button, on some modern Intel Skylake notebook and partly also on some older Lenovo machines, e.g. X201. Additionally, we added support to reset and power-off machines via ACPI. ACPI state changes are reported by the acpica application by setting the config attribute 'report' to "yes". ! ! ! ... Whenever such a state change is detected, the application generates the appropriate report named 'acpi_lid', 'acpi_ac', 'acpi_battery', 'acpi_ec' or 'acpi_fixed'. The detailed content of the reports is documented in the README of app/acpica or can be manually experienced by trying out the _acpica.run_ script in the libports repository. In order to reset or to power-off machines, the config attribute 'reset' respectively 'poweroff' must be set to "yes", as shown before. If one of both attributes is configured, app/acpica opens a ROM session called "system" and monitors changes of that ROM. The ROM must be XML in the following form: ! If the state attribute is set to "reset" or to "poweroff", app/acpica will try to reset respectively power-off the machine immediately. The operation may fail if the hardware resources are owned by some other components in the Genode system. E.g., on some machines we tested, the reset operation fails because the required I/O ports are owned and are used by the x86 platform driver. For such cases, we extended the platform driver by an additionally config parameter "system" which must be set to "yes", e.g.: ! ! ... ! ! ... With this configuration in place, the platform driver also opens and monitors the "system" ROM session and reacts upon a state change to "reset". If the platform driver owns the required I/O ports, it will trigger the ACPI reset. In the current state, we still use our old simple ACPI driver to detect basic necessary information for the x86 platform driver. The ACPI driver reports all findings in form of a report, which is provided as a ROM session to the platform driver. Later on, after the platform driver has announced its service, the acpica application takes over the ACPI functionality of our old ACPI driver and takes care of all dynamic ACPI events. It first looks a bit cumbersome, however the reasons are twofold. First, we wanted to start to experiment with the acpica library without putting our ACPI driver at danger. Second, we wanted to see where the complexity of the additionally ACPI features leads us. If one is using sloccount, or cloc, as complexity measure and applies the tool to the respectively folders, the following numbers show up: ! repos/os/src/driver/acpi/ ~1000 ! contrib/acpica-/ ~120000 ACPICA library ! repos/libports/src/lib/acpica/ ~600 Genode-specific ACPICA libary support code ! repos/libports/src/app/acpica/ ~1000 application using the ACPICA Genode port Of course, the numbers are inaccurate and the comparison is unfair since we do not take into account, which files of the acpica library are actually in use. Furthermore we can get more functionality with the acpica library, which we never could achieve with our own basic ACPI driver implementation. However, the point here to be made is, that we have to add much complexity to get a full ACPI capable system and that solely a small amount of the complexity actually is really required to drive an operating system like Genode. Generalized SDHCI driver ======================== The SDHCI driver was originally created for the Raspberry Pi. However, the same host controller is used also in other platforms, in particular Xilinx Zynq. Hence, the existing driver was generalized to become usable on such platforms. Thanks to Timo Wischer for this contribution. Libraries and applications ########################## LxIP update =========== LxIP is the port of the Linux TCP/IP stack as a library on Genode. Along with the work described in Section [Linux kit], LxIP was updated to Linux version 4.4.3 and uses the lx_kit now. Qemu USB ======== The QEMU USB library handles EP stalls now. In particular, this fix enables the use of USB storage devices in VirtualBox that do not support certain SCSI commands, e.g. READ_FORMAT_CAPACITY, and will stall if they receive such a command. Windows guests typically use the aforementioned command to check if the USB storage device in question is in fact an USB floppy drive. Platforms ######### Generalization of platform-specific headers =========================================== In anticipation of the planned binary compatibility of Genode components across different kernels, we unified most parts of Genode's base API and largely removed the dependency on platform-specific types. The most profound change is the interface of the IPC library, which used to depend on platform-specific message-buffer layouts. Besides unifying the message buffer classes across all platforms, we reconsidered the roles of the IPC-library classes such as 'Ipc_marhsaller', 'Ipc_server', and 'Ipc_client'. This led to several additional simplifications in the server-loop implementations, which makes the flow of control and information much more obvious, yet is also more flexible. I.e., on NOVA, we don't even have the notion of reply-and-wait. Now, we are no longer forced to pretend otherwise. NOVA microhypervisor ==================== The kernel received minor adjustments because of the ACPI work. One curious performance issue, we actually detected and hunted before our ACPICA library work. It happens that a modern Intel Skylake notebook (Core i 6th generation) running Genode/NOVA scenarios like noux tool-chain or Virtualbox performed really bad - sometimes it was only as fast as a 1th generation Intel Core CPU as used in X201 notebooks. After some mysterious hunting of possible reasons, it finally turned out that the UEFI vendor did not disable ACPI GPE (General Purpose Events) events properly when handing over control to the boot loader and kernel. As soon as the NOVA kernel enabled the ACPI interrupt (normally IRQ 9) because it utilizes the ACPI PM timer feature, the kernel got a storm of GPE interrupts, which got not handled properly. Still the system was alive and made progress, but the performance was really bad. We changed the kernel to disable all event sources enabled in the ACPI GPE0/1 registers. Beside that, using the acpica application also solves the performance issue, since the library also resets the GPE registers during initialization. However, currently the acpica application is optional and not loaded in all scenarios. On 64 bit, NOVA supports the so called PCID feature, aka tagged TLB. The hardware actually supports up to 4096 processes at a time, which can be used with tagged TLBs. Unfortunately the original PCID allocator wrapped after 4096 PCIDs, which caused - beginning with the 4097th process - to accidentally re-use the same PCIDs and therefore the same TLB entries of long living processes, like kernel, core, init, and drivers. This leads to the interesting phenomena of bugs. We changed the allocator from a monotonic increasing number to a bit allocator, maintaining the used and free PCIDs more accurately. Additionally, we extended the kernel to support scenarios on Genode where capabilities are forwarded from a capability sender to a capability receiver through one or more intermediary components (like servers). In such scenarios, the intermediary components don't need the forwarded capability for some reasons and want to free and re-use the used capability index. Unfortunately, or actually intentionally, the syscall 'revoke' will not just revoke the local capability but all subsequent derived capabilities. Because of this kernel behaviour, we had several quirks in Genode/base-nova, especially in the user level capability map implementation and in the Genode entrypoint reply handling code to deal with such situations. With all the Genode base API changes and unification efforts of all Genode base platforms, the quirks became obvious obstacles. With this release, we added support to the kernel, to just locally 'drop' the accessibility to the unneeded capability, but not the accessibility of the so far subsequent derived capabilities. With the kernel extension, we were able to remove the mentioned base-nova quirks. Execution on bare hardware (base-hw) ==================================== For running Genode scenarios on our custom kernel (base-hw), two hardware timers are needed. One timer is used by the kernel as the basis for the preemptive scheduling. The other timer is used by the user-level timer driver as the timing source for user-level components. On NOVA, we gathered good experiences with using the kernel's scheduling timer as the basis for the user-level timer. Eliminating the need for a real timer device driver (like for the PIT on x86) reduces the overall complexity. The interrupt load becomes lower without the userland triggering timer interrupts. And since the kernel uses CPU-core-local timers (i.e. the local APIC timer on x86) as opposed to a global timer in the userland, expensive cross-CPU-communication is avoided. With the current release, we applied the lessons learned to our base-hw kernel. As a further motivation, the removal of the dependency on a timer device clears the way to run multiple Genode instances on top of the Muen separation kernel. The timeout feature has the form of a new 'timeout' system call that binds a signal context to a timeout. Hence, timeouts are delivered asynchronously, like interrupts, to the user-level timer service. The actual time can be requested via the 'timeout_age_us' system call, which returns the time since the last timeout was installed. Linux ===== The main purpose of Linux as Genode base platform are rapid prototyping and the development of components that do not depend on specific hardware properties. During early development (at least with C++) the most prevalent fatal bugs result in segmentation faults due to invalid pointers or insufficient stack size. Unfortunately, our platform code for Linux did not disclose much information about the exceptions that may occur and even remained silent about errors in some situations. With this release, we improve the exception-signal handling and use an alternate signal stack. The alternate stack ensures in almost all cases that Linux applications are able to handle exceptions including segmentation faults caused by stack overflows. We also enabled this facility for hybrid Linux applications. Tools and build system ###################### Usability improvements of the ports tools ========================================= The ports tool set introduced in [https://genode.org/documentation/release-notes/14.05#Management_of_ported_3rd-party_source_code - Genode 14.05] has become an integral part of the work flow for Genode developers. With the current release, we improve the usability of the _prepare_port_ tool in two respects. First, the tool now accept a list of ports instead of merely a single argument. This alleviates the need to manually re-execute the tool with different arguments. Second, if the build system encounters a missing port, it no longer backs out immediately but collects all the (potentially more than one) missing ports that are required for the build. It then presents the user with a ready-to-use command to install all missing ports at once, which greatly improves the experience of working with sophisticated system scenarios. For example, when attempting to execute the _virtualbox.run_ script with a freshly cloned Genode source tree, the build system produces the following error message: !Error: Ports not prepared or outdated: ! dde_linux libc libiconv nova qemu-usb stdcxx virtualbox x86emu ! !You can prepare respectively update them as follows: ! .../prepare_port dde_linux libc libiconv nova qemu-usb stdcxx virtualbox x86emu Furthermore, one may state the number of ports that shall be prepared in parallel at a max by using the -j parameter. If -j is not set by the user, the tool acts as with -j1. Since the _prepare_ports_ tool has completely replaced the former "make prepare" mechanism, we finally removed the last traces of the old mechanism in the form of the makefiles present in the respective source-code repositories. Updated tool chain ================== Genode 16.05 requires a tool-chain update, which can be downloaded as [https://sourceforge.net/projects/genode/files/genode-toolchain/ - precompiled binary archive] for 32-bit and 64-bit Linux or built according to the [https://genode.org/download/tool-chain - tool-chain documentation]. With the updated tool chain, we enable the '__cxa_demangle()' function to be able to print user-readable names of uncaught exceptions. In the course of our GDB improvements, we enhance the x86 debugging support for 64-bit and update the required GDB tools. Furthermore, we added the RISC-V relevant tools to the binary archive to ease developing Genode components for this platform. Removal of stale features ######################### We originally added chroot support to the Linux version of Genode to accommodate the use of Genode as middleware on Linux. We enabled the configuration of custom UIDs, GIDs, and chroot paths for components started by init. However, apart from a brief period of time when we experimented with the idea, it is no longer pursued. Now, with our aspiration to attain binary compatibility across kernels, we removed the Linux-specific chroot support.