How to start exploring Genode

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

• libsdl2-dev, libdrm-dev, and libgbm-dev (needed to run interactive system scenarios directly on Linux)

• 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 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:

1. Download the kernel:

    cd <genode-dir>
    ./tool/ports/prepare_port okl4
   

2. Create a build directory

    ./tool/create_builddir x86_32
   

3. Uncomment the following line in x86_32/etc/build.conf

    REPOSITORIES += $(GENODE_DIR)/repos/libports
   

4. 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: