genode/ports-foc/README

This repository contains the port of L4Linux/L4Android for Genode.

L4Linux is a para-virtualized version of Linux running on top of the
micro-kernel Fiasco.OC. The original code uses the L4RE framework. This package
contains a small L4Linux support library as well as a patch for L4Linux, that
replaces L4RE by the Genode framework. Nevertheless, L4Linux stays to be
dependent on Fiasco.OC, meaning that you can only use it in combination with
Genode running on top of Fiasco.OC.

L4Android is a fork of L4Linux which in addition comprises the Android kernel
patches.


Quickstart
==========

L4Linux on Genode/Fiasco.OC IA32
----------------------------------
Prepare this repository:

! make prepare

Create a new build-directory:

! <path_to_genode_repo>/tool/create_builddir foc_x86_32 BUILD_DIR=l4linux

Edit the 'etc/build.conf' file in your build directory, and uncomment the following
lines:

! REPOSITORIES += $(GENODE_DIR)/ports-foc
! REPOSITORIES += $(GENODE_DIR)/dde_ipxe

Optionally, add an appropriate '-j' option to the make command in the same file:

! MAKE += -j4

Go to your newly created build directory, and execute the run-script for L4Android:

! make run/l4linux

L4Android on Genode/Fiasco.OC IA32
----------------------------------
Prepare this repository:

! make prepare TARGET=l4android

Create a new build-directory:

! <path_to_genode_repo>/tool/create_builddir foc_x86_32 BUILD_DIR=l4android

Edit the 'etc/build.conf' file in your build directory, and uncomment the following
lines:

! REPOSITORIES += $(GENODE_DIR)/ports-foc
! REPOSITORIES += $(GENODE_DIR)/dde_gpxe

Please do not forget to issue 'make prepare' in the 'dde_ipxe' and 'base-foc'
repositories.
Optionally, add an appropriate '-j' option to the make command in the same file:

! MAKE += -j4

Normally, Genode applications for Fiasco.OC are started without KVM support in
Qemu as we ran into trouble with KVM/Fiasco.OC in the past. Nevertheless, using
Android without KVM-support gets sometimes painful with regard to the boot-time,
so feel to add the following line in 'etc/build.conf':

! QEMU_OPT = -no-kvm-irqchip

Go to your newly created build directory, and execute the run-script for L4Android:

! make run/l4android

That's it! In addition to using the graphical interface of Android in the framebuffer
window, provided by Qemu, you can use a Linux shell in the terminal
that runs the 'make' command, and you can connect to the Fiasco.OC's kernel debugger
via a serial connection that is established as a pipe in '/tmp/qemu-pipe'.


Detailed instructions
=====================

Fiasco.OC prerequisites
-----------------------

If you haven't build Genode for Fiasco.OC yet, please refer to the following
document:

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

Preparing the L4Linux/L4android kernel source code
--------------------------------------------------

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

! make prepare

If you like to build the L4Android kernel version as well, additionally type:

! make prepare TARGET=l4android

Afterwards you need to include the L4Linux 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.

Building and running L4Linux/L4android
--------------------------------------

Now, you can change to your build directory and issue:

! make l4linux

If you want to build the L4Android kernel, instead type:

! make l4android

The 'bin/' directory within your build directory should now contain a symbolic
link to the L4Linux resp. L4Android binary.

To test your Linux binary, you also need to tweak the config file for init and
potentially your bootloader script. You will find examples for this in the
'config/' directory of this repository.

For a quick test of running L4Linux with Genode you can execute the Genode run
script 'ports-foc/run/l4linux.run' or 'ports-foc/run/l4android.run' by issuing
one of the following commands from the Genode build directory:

! make run/l4linux

or:

! make run/l4android

The run script will build all executables including the L4Linux kernel,
downloads necessary system images, performs the integration of all components
into a bootable image, and boot the image in Qemu. To inspect those individual
steps more closely, please refer to the run script and the Fiasco.OC specific
run environment implemented in 'base-foc/run/env'.

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

You can state the Linux kernel command line by using the XML configuration of
the start entry of your Linux instance, e.g.:

! <config args="mem=64M l4x_rd=initrd.gz"/>

Nic session connection
----------------------

When you provide a nic service to your L4Linux instance, the kernel will auto-detect
that, and runs a nic-driver, which will provide the nic-session as ethernet device
'eth0'. Currently, only one nic-session per instance is supported.

Terminal session
----------------

When providing a terminal-session to your Linux instance, it will automatically
register an appropriated serial and console driver in the kernel, that is
available as device 'ttyS0'. Currently, only one such device instance is supported.

Block session connection
------------------------

To use a block session of the underlying Genode system, we provide a special
block-driver stub in L4Linux. You need to state how much block devices you want
to use, and their name internally used by Linux, e.g.:

! <config>
!   <block label="sda"/>
!   <block label="sdb"/>
! <config/>

Initramfs
---------

If you need to start Linux with an initramfs, you have to provide the name of the
archive within the kernel command line, such as:

! "l4x_rd=initrd.gz"

You can find a working example initramfs for here:

:[http://genode.org/files/release-11.11/l4lx/initrd-ia32.gz]
  _initramfs for the x86 architecture_

:[http://genode.org/files/release-11.11/l4lx/initrd-arm.gz]
  _initramfs for the ARM architecture_

Configuring Linux
-----------------

This L4Linux package contains a minimal Linux configuration that should work
out of the box. Hardware drivers are disabled as Genode doesn't allow Linux
to directly access device hardware. If you want to enable/disable options in
Linux, you can do so by using the normal Linux build system. You will find the
'.config' file Linux is using within the 'l4linux/' directory of your build
directory. If you don't want to tweak '.config' directly, you can also change
to the 'l4linux/' directory of your build directory and issue:

! make menuconfig

Then you will get the well known ncurses interface.

When manually changing the Linux configuration for ARM platforms, you need
to additionally specify the corresponding 'L4ARCH' value at the command line:

! make menuconfig L4ARCH=arm

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

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

! VERBOSE_LX_MK=1 make l4linux