=============================================
        How to use Genode with the Fiasco microkernel
        =============================================


               Norman Feske, Christian Helmuth

Abstract
########

This documentation describes the process of building and booting the L4/Fiasco
version of Genode. It assumes that you are familiar with basic concepts
described in the introductory documentation of Genode, namely the "How to start
exploring Genode" document.


Preconditions
#############

The Fiasco version of Genode relies on the following components from
the source tree of the Fiasco microkernel and the L4 environment (which also
need additional tools).


Tools
=====

* Gawk
* Bison
* Byacc
* Python


The Fiasco microkernel
======================

Information about Fiasco are provided at its official website:

! http://os.inf.tu-dresden.de/fiasco/prev/

To download the kernel and integrate it with Genode, issue the following
command from within the toplevel directory:

! ./tool/ports/prepare_port fiasco

For the vesa driver on x86 the x86emu library is required and can be downloaded
and prepared by invoking the following command:

! ./tool/ports/prepare_port x86emu

This command will download a prepackaged version of the kernel tested
with Genode. The build process of the kernel is integrated with Genode's
build system. After creating a build directory using 'create_builddir'
with 'fiasco_x86' as argument:

! <genode-dir>/tool/create_builddir fiasco_x86 \
!   BUILD_DIR=<build-dir>

From within the new <build-dir>, the kernel can be compiled via

! make kernel

When using Genode's run mechanism, there is no need to explicitly
build the kernel. The run environment (see 'base-fiasco/run/env')
takes care of it. So you can simple execute run scripts from within
the build directory, for example:

! make run/demo


Behind the scenes
=================

For using the L4/Fiasco kernel, some basic user-level components and libraries
are needed. These are subsumed under the name L4 environment an are organized
as a number of packages. These packages provide two types of components.  There
are low-level components for booting up and interfacing to Fiasco and there are
higher-level components that compose a basic OS infrastructure. For Genode, we
only rely on the low-level packages.

Previous versions of Genode included all necessary sources from the L4
environment in the '3rd/fiasco/snapshot' subdirectory. From release 10.02, the
'3rd' directory is no longer part of the release archive and also removed from
the subversion repository. Please download the '3rd_fiasco.tar.bz2' archive.
The source are organized as follows

:'tool': contains the tools that are used by the build processes of
  the L4 environment and Fiasco. For example, the build process of Fiasco
  relies on the 'preprocess' tool.

:'kernel': contains the Fiasco microkernel.

:'l4': contains the L4-environment source tree. The single packages
  are located at 'l4/pkg'.

From all the packages of the L4 environment, the following three are of
interest for using Genode:

:'pkg/l4sys': contains the Fiasco system-call bindings.

  The system-call bindings are a set of C-header files that define the
  application-programming interface for invoking the system calls of
  Fiasco.

:'pkg/sigma0':

  Sigma0 is the initial memory manager required to use Fiasco.

:'pkg/bootstrap':

  Bootstrap is the program that is started by the boot loader.
  After being started, Bootstrap prepares the bare machine to
  accommodate Fiasco. On many embedded architectures, bootstrap
  is used to create a single binary image containing all boot-time
  OS components.

To build all components under '3rd/fiasco' after extracting the
archive, issue the following commands:

! mkdir <build-dir>
! make -C 3rd/fiasco BUILD_DIR=<build-dir>/3rd build

The specified '<build-dir>' must be the absolute path to the
directory, which will contain the build directories for the third party
software and the Genode build directory. After the build, your compound
build directory contains the following subdirectories:

:'fiasco_x86':

  All generated files and the final binary of Fiasco reside here.

:'l4env':

  L4 environment binaries and header files.