======================================
                How to use Genode directly on hardware
                ======================================

                            Martin Stein

Abstract
########

This document provides brief instructions about building and booting Genode
with the 'base-hw' repository. The 'base-hw' repository provides an
implementation of the Genode core that runs directly on hardware, without an
intermediate third-party kernel. It supports a limited range of target boards.
For further target specific informations, have a look at
'<GENODE_DIR>/repos/base-hw/doc/<TARGET>.txt' where '<TARGET>'
is one of the following:

'pbxa9'    - Realview PBXA9
'vea9x4'   - Versatile Express A9X4
'imx31'    - Freescale i.MX31
'panda'    - PandaBoard A2


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

To build Genode 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

If you want to use the so called run-scripts in Genode, a mechanism that
automates building, integration and testing of components, you have to install
the following, additional package:

! apt-get install expect

If you want to examine the examples that are given in this document, you will
need Qemu for ARM emulations to run them on your machine:

! apt-get install qemu-kvm-extras


Building Genode to run directly on hardware
###########################################

The current version of the Genode source code is available at this page:

:http://genode.org/download/repository:
  Donwloading the Genode source code

Now, go to a directory where you want the Genode build directory to
remain. Use the helper script in the 'tool' directory of the Genode
source tree to create the initial build environment. You need to state the
build directory you want to create, and the hardware target to run Genode on.

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

Where '<TARGET>' is one of the following, depending on the hardware system
you aim at:

'pbxa9'    - Realview PBXA9
'vea9x4'   - Versatile Express A9X4
'imx31'    - Freescale i.MX31
'panda'    - PandaBoard A2

Please notice that not all of these targets might be emulateable with Qemu.
To be on the safe side use 'pbxa9'. For informations about how to boot
'base-hw' images on real hardware have a look at
'<GENODE_DIR>/repos/base-hw/doc/<TARGET>.txt'.

Now, go to the newly created build directory make a test:

! cd <build-dir>
! make run/nested_init

This will build the Genode components that are needed to run a simple test
with 3 nested init programs, and than execute it via Qemu.