genode/ports-okl4/README

This repository contains the port of OKLinux for Genode.

OKLinux is a para-virtualized version of Linux running on top of the
micro-kernel OKL4. The original code uses the Iguana framework - a bunch of
server components and libraries to simplify construction of applications
running on top of OKL4. This package contains a small OKLinux support library,
as well as a patch for OKLinux, that replaces Iguana by the Genode framework.
Nevertheless, OKLinux stays to be dependent on OKL4, meaning that
you can only use it in combination with Genode running on top of OKL4.

Usage
-----

If you haven't build Genode for OKL4 yet, please refer to the following documents:

:[http://genode.org/community/wiki/GenodeOnOKL4 - Genode on OKL4 Wiki page]:
  This Wiki page contains the information on how to build and use
  Genode with OKL4.

For building OKLinux for Genode, you first need to download and patch the
original sources. The top-level makefile of this repository automates this
task. Just issue:

! make prepare

Afterwards you need to include the OKLinux repository into the Genode build
process. Just add the path to this directory to the 'REPOSITORIES' declaration
of the 'etc/build.conf' file within your build directory.
Now, you can change to your build directory and simply type:

! make oklinux

That's all. The 'bin/' directory within your build directory should now contain
a symbolic link to the 'vmlinux' binary.
To test your Linux binary, you also need to tweak the config file for init and
for the elfweaver tool. You will find examples for this in the 'config/'
directory of this repository.

Block, net and audio driver
---------------------------

OKLinux for Genode provides special drivers, that provide an audio-card,
network-card and block-device to Linux applications. They are based on
the block-, nic- and audio-out-session interface of Genode.

The drivers are compiled in by default, but needs to be enabled in the
XML configuration of OKLinux, like so:

! <config>
!      <block/>
!      <audio/>
!      <nic/>
! </config>

The block device gets available under the name 'sda', like traditionally
scsi, ata and sata disks under Linux. The nic is available as the first
ethernet device 'eth0'. The audio-card is available as a simple ALSA device.

Kernel command line
-------------------

You can state the Linux kernel command line by using the XML configuration of
the start entry of your OKLinux instance:

! <config>
!      <commandline args="root=/dev/gda1"/>
! </config>

Initrd
------

If you need to start Linux with an initramfs, you have to provide the name of the
archive within the config area of your Linux instance:

! <config>
!      <initrd name="initrd-2.6.23.gz"/>
! </config>

Of course, you need to add this archive-file to the list of rom-files provided.

Screens
-------

Genode's version of OKlinux does include a special screen driver, which maps
framebuffer, input and/or nitpicker sessions to Linux's framebuffer device and
input event device interfaces.
A single screen is either a conglomerate of native framebuffer and input session,
or framebuffer and input sessions of a nitpicker session. To enable one or more
devices in Linux use the 'screens' section in your XML configuration:

! <config>
!       <screens>
!             <framebuffer/>
!             <nitpicker/>
!       </screens>
! </config>

The order in the 'screens' section determine the order of visible devices in Linux.

Configure Linux
---------------

This OKLinux package contains only a minimal Linux configuration. Especially,
any hardware drivers are missing, as Genode/OKL4 doesn't allow direct hardware
access from Linux. If you want to enable/disable options in Linux, you can
simply do so by using the normal Linux build system. You will find the
'.config' file Linux is using within the 'oklinux/' directory of your build
directory. If you don't want to tweak '.config' directly, you can also change
to the 'oklinux/' directory of your build directory and issue:

! ARCH=l4 SYSTEM=i386 make menuconfig

Then you will get the well known ncurses interface.

Troubleshooting
---------------

If you run into problems when building OKLinux and you want the build process
to be somehow more verbose, you can build OKLinux this way:

! VERBOSE_LX_MK=1 make oklinux