genode/ports-foc
Stefan Kalkowski d287b9d893 Fiasco.OC: introduce Cap_index (fixes #149, #112)
This commit introduces a Cap_index class for Fiasco.OC's capabilities.
A Cap_index is a combination of the global capability id, that is used by Genode
to correctly identify a kernel-object, and a corresponding entry in a
protection-domain's (kernel-)capability-space. The cap-indices are non-copyable,
unique objects, that are held in a Cap_map. The Cap_map is used to re-find
capabilities already present in the protection-domain, when a capability is
received via IPC. The retrieval of capabilities effectively fixes issue #112,
meaning the waste of capability-space entries.
Because Cap_index objects are non-copyable (their address indicates the position
in the capability-space of the pd), they are inappropriate to use as
Native_capability. Therefore, Native_capability is implemented as a reference
to Cap_index objects. This design seems to be a good pre-condition to implement
smart-pointers for entries in the capability-space, and thereby closing existing
leaks (please refer to issue #32).

Cap_index, Cap_map, and the allocator for Cap_index objects are designed in a way,
that it should be relatively easy to apply the same concept to NOVA also. By now,
these classes are located in the `base-foc` repository, but they intentionally
contain no Fiasco.OC specific elements.

The previously explained changes had extensive impact on the whole Fiasco.OC
platform implementation, due to various dependencies. The following things had to
be changed:

* The Thread object's startup and destruction routine is re-arranged, to
  enable another thread (that calls the Thread destructor) gaining the
  capability id of the thread's gate to remove it from the Cap_map, the
  thread's UTCB had to be made available to the caller, because there
  is the current location of that id. After having the UTCB available
  in the Thread object for that reason, the whole thread bootstrapping
  could be simplified.
* In the course of changing the Native_capability's semantic, a new Cap_mapping
  class was introduced in core, that facilitates the establishment and
  destruction of capability mappings between core and it's client's, especially
  mappings related to Platform_thread and Platform_task, that are relevant to
  task and thread creation and destruction. Thereby, the destruction of
  threads had to be reworked, which effectively removed a bug (issue #149)
  where some threads weren't destroyed properly.
* In the quick fix for issue #112, something similar to the Cap_map was
  introduced available in all processes. Moreover, some kind of a capability
  map already existed in core, to handle cap-session request properly. The
  introduction of the Cap_map unified both structures, so that the
  cap-session component code in core had to be reworked too.
* The platform initialization code had to be changed sligthly due to the
  changes in Native_capability
* The vcpu initialization in the L4Linux support library had to be adapted
  according to the already mentioned changes in the Thread object's bootstrap
  code.
2012-03-22 14:10:44 +01:00
..
config Imported Genode release 11.11 2011-12-22 16:19:25 +01:00
include Bump year in copyright headers to 2012 2012-01-03 15:35:05 +01:00
lib/mk Imported Genode release 11.11 2011-12-22 16:19:25 +01:00
mk Imported Genode release 11.11 2011-12-22 16:19:25 +01:00
patches Imported Genode release 11.11 2011-12-22 16:19:25 +01:00
run Adapt memory quota to recent Fiasco.OC changes 2012-03-06 17:02:48 +01:00
src Fiasco.OC: introduce Cap_index (fixes #149, #112) 2012-03-22 14:10:44 +01:00
Makefile Imported Genode release 11.11 2011-12-22 16:19:25 +01:00
README Imported Genode release 11.11 2011-12-22 16:19:25 +01:00

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 name="sda"/>
!   <block name="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