A simple system scenario

The build directory offers much more than an environment for building components. It supports the automation of system-integration work flows, which typically include the following steps:

Building a set of components,
Configuring the static part of a system scenario,
Assembling a boot directory with all ingredients needed by the scenario,
Creating a boot image that can be loaded onto the target platform,
Booting the target platform with the boot image,
Validating the behavior of the scenario.

The recipe for such a sequence of steps can be expressed in the form of a so-called run script. Each run script represents a system scenario and entails all information required to reproduce the scenario. Run scripts can reside within the run/ subdirectory of any source-code repository.

Genode comes with a ready-to-use run script showcasing a simple graphical demo scenario. The run script is located at <genode-dir>/repos/os/run/demo.run. It leverages Genode's package-management tools for assembling a static system image. The package management is explained in detail in Section Package management. For now, we can skip the details by instructing the build system to automatically create packages and update their version numbers for us. Uncomment the following line in the build/x86_64/build.conf file:

 RUN_OPT += --depot-auto-update

In contrast to the building of individual components as described in the previous section, the integration of a complete system scenario requires us to select a particular OS kernel to use. The following command instructs the build system to build, integrate, and start the "run/demo" scenario on the Linux kernel:

 make run/demo KERNEL=linux BOARD=linux

The command prompts the build system to lookup a run script called demo.run in all repositories listed in etc/build.conf. It will eventually find the run script within the os/ repository. After completing the build of all components needed, the command will then automatically start the scenario. Because the build directory was created for the x86_64 platform and we specified "linux" as KERNEL, the scenario will be executed directly on the host system where each Genode component resides in a distinct Linux process. To explore the scenario, follow the instructions given by the graphical tutorial browser.

The terminal where the make run/demo command was issued displays the log output of the Genode system. To cancel the execution, hit control-c in the terminal.

Targeting a microkernel

Whereas the ability to run system scenarios on top of Linux allows for the convenient and rapid development of components and protocols, Genode is primarily designed for the use of microkernels. The choice of the microkernel to use is up to the user of the framework and may depend on various factors like the feature set, the supported hardware architectures, the license, or the development community. To execute the demo scenario directly on the NOVA microhypervisor, the following preparatory steps are needed:

Download the 3rd-party source code of the NOVA microhypervisor
```
 <genode-dir>/tool/ports/prepare_port nova
```
The prepare_port tool downloads the source code of NOVA to a subdirectory at <genode-dir>/contrib/nova-<hash>/ where <hash> uniquely refers to the prepared version of NOVA.
On real hardware, the scenario needs a framebuffer driver. The VESA driver relies on a 3rd-party x86-emulation library in order to execute the VESA BIOS code. Download the 3rd-party source code of the x86emu library:
```
 <genode-dir>/tool/ports/prepare_port x86emu
```
The source code will be downloaded to <genode-dir>/contrib/x86emu-<hash>/.
To handle USB devices, a device-driver environment for executing a Linux kernel subsystem as a user-level component is used. Download the 3rd-party source code of the dde_linux repository:
```
 <genode-dir>/tool/ports/prepare_port dde_linux linux
```
The source code will be downloaded to <genode-dir>/contrib/dde_linux-<hash>/ and <genode-dir>/contrib/linux-<hash>/ respectively.
To boot the scenario as an operating system on a PC, a boot loader is needed. The build process produces a bootable disk or ISO image that includes the GRUB2 boot loader as well as a working boot-loader configuration. Download the boot loader as ingredient for the image-creation step.
```
 <genode-dir>/tool/ports/prepare_port grub2
```
Since NOVA supports the x86_64 architecture of our build directory, we can keep using the existing build directory that we just used for Linux. However, apart from enabling the parallelization of the build process as mentioned in Section Using the build system, we need to incorporate the libports, dde_linux, and pc source-code repositories into the build process by uncommenting the corresponding lines in the configuration. Otherwise the build system would fail to build the VESA and USB HID drivers, which reside within libports/, dde_linux/, and pc/ respectively.

With those preparations in place, issue the execution of the demo run script from within the build directory:

 make run/demo KERNEL=nova BOARD=pc

This time, an instance of Qemu will be started to execute the demo scenario. The Qemu command-line arguments appear in the log output. As suggested by the arguments, the scenario is supplied to Qemu as an ISO image residing at var/run/demo.iso. This ISO image can not only be used with Qemu but also with a real machine. For example, creating a bootable USB stick with the system scenario is as simple as writing the ISO image onto an USB stick:

 sudo dd if=var/run/demo.iso of=/dev/<usb-device> bs=8M conv=fsync

Note that <usb-device> refers to the device node of an USB stick. It can be determined using the dmesg command after plugging-in the USB stick. For booting from the USB stick, you may need to adjust the BIOS settings of the test machine accordingly.