genode/repos/base-okl4/doc/okl4.txt

                        ==============================
                        Genode on the OKL4 microkernel
                        ==============================


                               Stefan Kalkowski


OKl4 is a microkernel developed and distributed by Open Kernel Labs. It is
focused on embedded devices. Genode support the OKL4 kernel version 2.1
on the x86_32 platform.

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


Prerequisites
#############

You need Python 2.4 to use the OKL4 build system. On Debian/Ubuntu systems
simply type:

! apt-get install python2.4

Since Ubuntu 10.04, the python2.4 package is no longer part of the official
repositories. However, you can manually add the repository via:

! add-apt-repository ppa:python24-team/python24
! apt-get update

Moreover, you need to download and install the tool-chain used by Genode. Have
a look at this page:

:[http://genode.org/download/tool-chain]:
  Genode tool-chain


Downloading and building the OKL4 kernel
########################################

To download the OKL4 source code, issue

! make prepare

from within the 'base-okl4' directory. The Makefile within this directory will
take care of downloading the kernel's source code and applying the patches
found at 'base-okl4/patches'.

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

To create a build directory for Genode running on OKL4, use the 'create_builddir'
tool:

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

Once, you have created the build directory, the OKL4 kernel can be built from
within '<build-dir>' via

! make kernel


Running the Genode demonstration scenario
#########################################

For a quick test drive of the OKL4 kernel, issue 'make run/demo' from the build
directory.


Manually building a boot image
##############################

This section is not needed when using Genode's run-script mechanism. The manual
steps described below are automatically executed via the OKL4 run environment
as found at 'base-okl4/run/env'.

To practically use the OKL4 kernel and applications running on top of it, Open
Kernel Labs provide a tool called 'elfweaver', that is used to merge different
application binaries and the kernel itself into one single elf binary that can
be executed by your bootloader, e.g. Grub.

To configure 'elfweaver' to merge the appropriated elf binaries you have to
provide an XML file. A good starting point is the 'weaver_x86.xml' file that
includes the Genode demo example. Simply copy that file to your Genode build
directory and adapt the 'file' attribute of the 'kernel' tag to the absolute
path of the OKL4 kernel we build previously.

! cp <path_to_genode_src>/base-okl4/tool/weaver_x86.xml weaver.xml

The corresponding line in your weaver.xml should look like this:

! <kernel file="<path_to_okl4_src>/build/pistachio/bin/kernel" xip="false" >

Before creating the image, we need to supply a Genode config file as well.
For a quick start, you can copy and rename the template provided 'os/config/demo'
to '<builddir>/bin/config'. Alternatively, you can assign another file to the
'filename' of the 'memsection' declaration for the config file in 'weaver.xml'.
Now, we can use 'elfweaver' to create the image. Go to the 'bin' directory in
the Genode build directory that contains all the binaries and invoke the
script.

! cd bin
! <path_to_okl4_src>/tools/pyelf/elfweaver merge --output=weaver.elf ../weaver.xml
! strip weaver.elf

Note: the given paths to the resulting elf file and the input xml file have to
be relative.

*Bug alert:* Elfweaver triggers an assertion when too many memsections are
declared in the 'weaver.xml' file and just outputs the following message
! An error occurred:
Apparently, elfweaver has a problem with calculating the size of the boot info
section. As a quick fix, you can increase the value of 'BOOTINFO_GUESS_OPS' in
'<okl4-dir>/tools/pyelf/weaver/bootinfo.py'.

The resulting elf image can be loaded by Grub now.


Further Information
###################

:[http://genode.org/documentation/articles/genode-on-okl4]:
  Article about the porting work of Genode to OKL4, featuring many technical
  insights that are useful to understand the peculiarities of this base platform.

:okl4_2.1.1-patch.9/README:
  OKL4 building guide

:[http://wiki.ok-labs.com]:
  OKL4 developer wiki

:[http://wiki.ok-labs.com/downloads/release-3.0/elfweaver-ref-manual-3.0.pdf]:
  Elfweaver reference manual