genode/base-pistachio/doc/pistachio.txt

               =========================================
               Genode on the L4ka::Pistachio microkernel
               =========================================


                            Norman Feske


Pistachio is the reference implementation of the L4 API version x.2 (also
referred to a v4). It is developed by the System Architecture Group at the
University of Karlsruhe, Germany and the DiSy group at the University of
New South Wales, Australia.

Because this kernel has been the experimentation platform for a lot of exciting
research experiments at the L4ka group and it is the basis for the commercial
version of L4 developed by OK-Labs, Pistachio is a very interesting base
platform for the Genode OS Framework.

The original port of the Genode OS Framework to Pistachio is the work of Julian
Stecklina who wanted to elaborate on the portability of the framework and
explore the use of Pistachio's multi-processor capabilities with Genode.

This document provides brief instructions about downloading, building and
booting the Pistachio version of Genode.


Downloading, building, and using L4ka::Pistachio
################################################

Please make sure that you haved downloaded and installed the tool chain,
which will be used for both, the L4ka::Pistachio kernel and Genode.

:[http://genode.org/download/tool-chain]:
  Preconfigured GNU tool chain for building Genode

To download the kernel source codes, issue 'make prepare' from within the
'base-pistachio' repository. This command will checkout the upstream Git
repository of the kernel. Please make sure to have Git installed.

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

! make prepare PKG=x86emu

After having successfully prepared the 'base-pistachio' repository and
'libports' you are ready to create a Genode build directory using the
'tool/create_builddir':

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

From within this directory, you can build the kernel by using 'make kernel'.
The kernel will be built within '<build-dir>/kernel/pistachio' using the Genode
tool chain.

To build and start Genode directly from within the Genode build directory,
issue

! make run/demo

This command will execute the steps described in the run script located at
'os/run/demo.run'. It will build all Genode components needed for the demo
scenario, create a configuration, and start the scenario using Qemu. To inspect
the individual steps more closely or learn the steps needed to manually
integrate Genode with L4ka::Pistachio, please revisit the Pistachio-specific
run environment at 'base-pistachio/run/env'.


Using an externally supplied kernel
###################################

It is possible to use a L4ka::Pistachio kernel that is manually downloaded
and built. To let Genode use an external kernel, create a file called
'<build-dir>/etc/pistachio.conf' with the following declarations:

! PISTACHIO_USER_BUILD_DIR = <location-of-pistachio/user/build>

The location of the Pistachio user-level build directory is the place where
Genode looks for the kernel-interface header files and the system bindings.

! PISTACHIO_KERNEL = <location-of-the-pistachio-kernel>

The specified kernel binary will be used when executing run scripts.