******************************
* HOWTO: ORE + ARPING + QEMU * 
******************************

This howto describes how to setup L4 running in QEmu with the ORe arping
example. For networking we will use one of QEmu's builtin network
interfaces and bridge it to the host Linux using a tun device.

Prerequisites
=============

L4-based
- --------
First of all we need to build the components necessary for running ORe. In
our example these are:

* The Fiasco kernel
* bootstrap, sigma0 and roottask
* log, names, dm_phys
* l4io, ore and ore_test_arping

For running ORe in QEmu we need to make sure that it contains a device
driver for one of the devices provided. In this example we'll use the
NE2000 driver which is available in both, ORe/DDE2.4 and ORe/DDE2.6.

Host computer
- -------------
* You need to have a tuntap driver for your host Linux available.
* You need to have installed the arping tool, that is able to ping ethernet
addresses. The Debian package for this is called arping.


Creating a menu.lst
===================
After building the system components, create a disk image where all your
binaries and config files reside. I will not describe this in detail here.

Edit the GRUB menu.lst entry and add an entry like this:

##########
# ORe and arping
##########
title [ore] Arping
kernel $(BINPATH)/bootstrap -serial
modaddr 0x02000000
module $(BINPATH)/fiasco $(FIASCO_OPT)
module $(BINPATH)/sigma0
module $(BINPATH)/roottask -symbols -lines -configfile task modname "ore"
allow_cli
module $(BINPATH)/Symbols
module $(BINPATH)/Lines
module $(BINPATH)/roottask.config
module $(BINPATH)/names
module $(BINPATH)/log
module $(BINPATH)/dm_phys
module $(BINPATH)/l4io
module $(BINPATH)/ore
module $(BINPATH)/ore_test_arping


Setting up networking and running QEmu
======================================

tuntap setup
- ------------
In order to bridge network packets between QEmu and our host Linux, we need
the tun device driver enabled in the kernel. Make sure that you either have
compiled this into the kernel itself or if it was compiled as a module, do:

$> modprobe tun

This will create a device /dev/net/tun. Your user needs to have read/write
privileges to this device in order to communicate with your QEmu instance.

Starting QEmu and L4
- --------------------
Now we can start QEmu. In addition to your normal command line parameters,
you need to add network-related options. My command line for the example
looks like this:

$> qemu -serial stdio -m 256 -net nic,vlan=0,model=ne2k_pci -net
tap,vlan=0,ifname=tap0 <image name>

This tells QEmu to set up a network interface with the NE2000 model and
creates a new network interface tap0 on your host to which all traffic from
this NIC is sent.

- From the GRUB menu.lst choose your arping entry. ORe and the arping example
will now boot. Indicators that everything goes well are in the log output:

ore     | main(): Initialized 2 network devices.
ore     | Device =   lo, IRQ =  0, MAC = 00:00:00:00:00:00
ore     | Device = eth0, IRQ = 10, MAC = 52:54:00:12:34:56

- -> If you see such lines, this means that ORe found 2 network devices. The
first one is the default loopback device, the second one is the QEmu network
device.

The arping client connects to ORe and then prints:

arping  | main(): opened eth0: 0 for 04:EA:43:01:96:09
..
arping  | main(): receiving...

- -> This means that the connection has been established. The client has been
allocated the MAC address  04:EA:43:01:96:09 and is now ready to receive
traffic with this ethernet address.

On the host
- -----------
Running ifconfig on your host will show you a new device such as this:

tap0      Link encap:Ethernet  HWaddr BA:0B:01:63:35:89
          inet addr:172.20.0.1  Bcast:172.20.255.255  Mask:255.255.0.0
          inet6 addr: fe80::b80b:1ff:fe63:3589/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:500
          RX bytes:0 (0.0 b)  TX bytes:468 (468.0 b)

This is the interface you are going to use for communication with QEmu. Now
you can ping the virtual machine (arping wants to be executed as root):

$> sudo arping -i tap0 04:EA:43:01:96:09
ARPING 04:EA:43:01:96:09
80 bytes from 255.255.255.255 (04:ea:43:01:96:09): icmp_seq=0
80 bytes from 255.255.255.255 (04:ea:43:01:96:09): icmp_seq=1
80 bytes from 255.255.255.255 (04:ea:43:01:96:09): icmp_seq=2
80 bytes from 255.255.255.255 (04:ea:43:01:96:09): icmp_seq=3
80 bytes from 255.255.255.255 (04:ea:43:01:96:09): icmp_seq=4
...
