xen/stubdom

                                IOEMU stubdom
                                =============

  This boosts HVM performance by putting ioemu in its own lightweight domain.

General Configuration
=====================

Due to a race between the creation of the IOEMU stubdomain itself and allocation
of video memory for the HVM domain, you need to avoid the need for ballooning,
by using the hypervisor dom0_mem= option for instance.


There is a sample configuration set in xmexample.hvm-stubdom and
xmexample.hvm-dm

In your HVM config "hvmconfig",

- use /usr/lib/xen/bin/stubdom-dm as dm script:

device_model = '/usr/lib/xen/bin/stubdom-dm'

- comment the disk statement:

#disk = [  'file:/tmp/install.iso,hdc:cdrom,r', 'phy:/dev/sda6,hda,w', 'file:/tmp/test,hdb,r' ]

- disable anything related to dom0, like pty serial assignments


Create /etc/xen/hvmconfig-dm (where "hvmconfig" is the name of your HVM
guest) with

kernel = "/usr/lib/xen/boot/ioemu-stubdom.gz"
vif = [ '', 'ip=10.0.1.1,mac=aa:00:00:12:23:34']
disk = [  'file:/tmp/install.iso,hdc:cdrom,r', 'phy:/dev/sda6,hda,w', 'file:/tmp/test,hdb,r' ]

where
- the first vif ('') is reserved for VNC (see below)
- 'ip=10.0.1.1,mac= etc...' is the same net configuration as in the hvmconfig
script,
- and disk = is the same block configuration as in the hvmconfig script.

Display Configuration
=====================

There are three posibilities

* Using SDL

  - In hvmconfig, disable vnc and sdl:

vnc = 0
sdl = 0

  - In hvmconfig-dm, set an sdl vfb:

vfb = [ 'type=sdl' ]

    by default qemu will use sdl together with opengl for rendering, if
    you do not want qemu to use opengl then also pass opengl=0:

vfb = [ 'type=sdl, opengl=0' ]

* Using a VNC server in the stub domain

  - In hvmconfig, set vnclisten to "172.30.206.1" for instance.  Do not use a
host name as Mini-OS does not have a name resolver.  Do not use 127.0.0.1 since
then you will not be able to connect to it.

vnc = 1
vnclisten = "172.30.206.1"

  - In hvmconfig-dm, fill the reserved vif with the same IP, for instance:

vif = [ 'ip=172.30.206.1', 'ip=10.0.1.1,mac=aa:00:00:12:23:34']

* Using a VNC server in dom0

  - In hvmconfig, disable vnc and sdl:

vnc = 0
sdl = 0

  - In hvmconfig-dm, set a vnc vfb:

vfb = [ 'type=vnc' ]

and any other parameter as wished.

To run
======

mkdir -p /exports/usr/share/xen/qemu
ln -s /usr/share/xen/qemu/keymaps /exports/usr/share/xen/qemu
mkdir -p /exports/var/lib
ln -s /var/lib/xen /exports/var/lib
/usr/sbin/fs-backend &

xm create hvmconfig



                                   PV-GRUB
                                   =======

  This replaces pygrub to boot domU images safely: it runs the regular grub
inside the created domain itself and uses regular domU facilities to read the
disk / fetch files from network etc. ; it eventually loads the PV kernel and
chain-boots it.
  
Configuration
=============

In your PV config,

- use /usr/lib/xen/boot/pv-grub.gz as kernel:

kernel = "/usr/lib/xen/boot/pv-grub.gz"

- set the path to menu.lst, as seen from the domU, in extra:

extra = "(hd0,0)/boot/grub/menu.lst"

you can also use a tftp path (dhcp will be automatically performed):

extra = "(nd)/somepath/menu.lst"

or you can set it in option 150 of your dhcp server and leave extra empty

Limitations
===========

- You can not boot a 64bit kernel with a 32bit-compiled PV-GRUB and vice-versa.
To cross-compile a 32bit PV-GRUB,

export XEN_TARGET_ARCH=x86_32

- bootsplash is supported, but the ioemu backend does not yet support restart
for use by the booted kernel.


                                Your own stubdom
                                ================

  By running

cd stubdom/
make c-stubdom

  or

cd stubdom/
make caml-stubdom

  you can compile examples of C or caml stub domain kernels.  You can use these
and the relevant Makefile rules as basis to build your own stub domain kernel.
Available libraries are libc, libxc, libxs, zlib and libpci.