JAILHOUSE
=========

Jailhouse is a partitioning Hypervisor based on Linux. It is able to run
bare-metal applications or (adapted) operating systems besides Linux. For this
purpose it configures CPU and device virtualization features of the hardware
platform in a way that none of these domains, called "cells" here, can
interfere with each other in an unacceptable way.

Jailhouse is optimized for simplicity rather than feature richness. Once
activated, it runs bare-metal, i.e. it takes full control over the hardware
and need no external support. However, in contrast to other bare-metal
hypervisors, it is loaded and configured by a normal Linux system. Its
management interface is based on Linux infrastructure. So you boot Linux
first, then you enable Jailhouse and finally you split off parts of the
system's resources and assign them to additional cells.


WARNING: This is work in progress! Don't expect things to be complete in any
dimension. Use at your own risk. And keep the reset button in reach.


Community
---------

Project home:   https://github.com/siemens/jailhouse

git:            https://github.com/siemens/jailhouse.git
                git@github.com:siemens/jailhouse.git

Mailing list:   jailhouse-dev@googlegroups.com
 Subscription:  jailhouse-dev+subscribe@googlegroups.com
                https://groups.google.com/forum/#!forum/jailhouse/join
 Archives:      http://news.gmane.org/gmane.linux.jailhouse


Requirements (preliminary)
--------------------------

currently:
 - Intel x86 processor with VMX support, more precisely
    - EPT (extended page tables)
    - unrestricted guest mode
 - at least 2 logical CPUs

upcoming:
 - Intel IOMMU with interrupt remapping support


Build
-----

Simply run make, optionally specifying the target kernel directory:

    make [KERNELDIR=/path/to/kernel/objects]

Note that the command line tool "jailhouse" requires a separate make run from
within the tools/ directory.


Configuration
-------------

Jailhouse requires one configuration file for the complete system and one for
each additional cell beside Linux. The configuration is currently being
defined manually by filling C structures. To study the structure, use
config/qemu-vm.c for a system configuration and config/minimal.c for a cell
configuration as reference. The build system will pick up every .c file from
the config/ directory and generate a corresponding .cell file. .cell files can
then be passed to the jailhouse command line tool for enabling the hypervisor
and creating new cells.


Demonstration in QEMU/KVM
-------------------------

The included system configuration qemu-vm.c can be used to run Jailhouse in
QEMU/KVM virtual machine on Intel x86 hosts. Currently it requires kvm.git,
next branch on the host (in order to get support for nested unrestricted guest
mode). 3.13 is expected to include all necessary feature for this test. You
also need a Linux guest image with a recent kernel (tested with >= 3.9) and
the ability to build a module for this kernel. Make sure the kvm-intel module
was loaded with nested=1 to enable nested VMX support. Start the virtual
machine as follows:

    qemu-system-x86_64 LinuxInstallation.img -m 1G -enable-kvm -serial stdio \
        -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx,+x2apic \
        -smp 4

Inside the VM, make sure that jailhouse.bin, generated by the build process,
is available for firmware loading (typically /lib/firmware). Load jailhouse.ko
and then enable Jailhouse like this:

    jailhouse enable /path/to/qemu-vm.cell

Next you can create a cell with a demonstration application as follows:

    jailhouse cell create /path/to/minimal.cell /path/to/apic-demo.bin \
        -l 0xf0000

apic-demo.bin is left by the built process in the inmate/ directory. This
application will program the APIC timer interrupt to fire at 10 Hz, measuring
the jitter against the PM timer and displaying the result on the 
console. Given that this demonstration runs in a virtual machine, obviously
no decent latencies should be expected.