README

   1 JAILHOUSE
   2 =========
   3
   4 Jailhouse is a partitioning Hypervisor based on Linux. It is able to run
   5 bare-metal applications or (adapted) operating systems besides Linux. For this
   6 purpose it configures CPU and device virtualization features of the hardware
   7 platform in a way that none of these domains, called "cells" here, can
   8 interfere with each other in an unacceptable way.
   9
  10 Jailhouse is optimized for simplicity rather than feature richness. Unlike
  11 full-featured Linux-based hypervisors like KVM or Xen, Jailhouse does not
  12 support overcommitment of resources like CPUs, RAM or devices. It performs no
  13 scheduling and only virtualizes those resources in software, that are essential
  14 for a platform and cannot be partitioned in hardware.
  15
  16 Once Jailhouse is activated, it runs bare-metal, i.e. it takes full control
  17 over the hardware and needs no external support. However, in contrast to other
  18 bare-metal hypervisors, it is loaded and configured by a normal Linux system.
  19 Its management interface is based on Linux infrastructure. So you boot Linux
  20 first, then you enable Jailhouse and finally you split off parts of the
  21 system's resources and assign them to additional cells.
  22
  23
  24 WARNING: This is work in progress! Don't expect things to be complete in any
  25 dimension. Use at your own risk. And keep the reset button in reach.
  26
  27
  28 Community
  29 ---------
  30
  31 Project home:   https://github.com/siemens/jailhouse
  32
  33 git:            https://github.com/siemens/jailhouse.git
  34                 git@github.com:siemens/jailhouse.git
  35
  36 Mailing list:   jailhouse-dev@googlegroups.com
  37  Subscription:  jailhouse-dev+subscribe@googlegroups.com
  38                 https://groups.google.com/forum/#!forum/jailhouse-dev/join
  39  Archives:      http://news.gmane.org/gmane.linux.jailhouse
  40
  41
  42 Requirements (preliminary)
  43 --------------------------
  44
  45 currently:
  46  - Intel x86 processor with support for 64-bit and VMX, more precisely
  47     - EPT (extended page tables)
  48     - unrestricted guest mode
  49     - preemption timer
  50  - Intel IOMMU (VT-d) with interrupt remapping support
  51    (except when running inside QEMU)
  52  - at least 2 logical CPUs
  53  - x86-64 Linux kernel (tested against >= 3.9)
  54     - VT-d IOMMU usage (DMAR) has to be disabled in the Linux kernel, e.g. via
  55       the command line parameter:
  56
  57           intel_iommu=off
  58
  59     - To exploit the faster x2APIC, interrupt remapping needs to be on in the
  60       kernel (check for CONFIG_IRQ_REMAP)
  61
  62
  63 Build
  64 -----
  65
  66 Simply run make, optionally specifying the target kernel directory:
  67
  68     make [KERNELDIR=/path/to/kernel/objects]
  69
  70 Note that the command line tool "jailhouse" requires a separate make run from
  71 within the tools/ directory.
  72
  73
  74 Configuration
  75 -------------
  76
  77 Jailhouse requires one configuration file for the complete system and one for
  78 each additional cell beside Linux. The configuration is currently being
  79 defined manually by filling C structures. To study the structure, use
  80 configs/qemu-vm.c for a system configuration and configs/apic-demo.c for a cell
  81 configuration as reference. The build system will pick up every .c file from
  82 the configs/ directory and generate a corresponding .cell file. .cell files can
  83 then be passed to the jailhouse command line tool for enabling the hypervisor
  84 and creating new cells.
  85
  86
  87 Demonstration in QEMU/KVM
  88 -------------------------
  89
  90 The included system configuration qemu-vm.c can be used to run Jailhouse in
  91 QEMU/KVM virtual machine on Intel x86 hosts. Currently it requires kvm.git,
  92 next branch on the host. 3.17 is expected to include all necessary features
  93 for this setup. QEMU is required in a recent version (2.1) as well if you want
  94 to use the configuration file included in the source tree.
  95
  96 You also need a Linux guest image with a recent kernel (tested with >= 3.9) and
  97 the ability to build a module for this kernel. Make sure the kvm-intel module
  98 was loaded with nested=1 to enable nested VMX support. Start the virtual
  99 machine as follows:
 100
 101     qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
 102         -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx,+x2apic \
 103         -drive file=LinuxInstallation.img,id=disk,if=none \
 104         -device ide-hd,drive=disk -serial stdio -serial vc
 105
 106 Inside the VM, make sure that jailhouse.bin, generated by the build process,
 107 is available for firmware loading (typically /lib/firmware).
 108
 109 The hypervisor requires a contiguous piece of RAM for itself and each
 110 additional cell. This currently has to be pre-allocated during boot-up. So you
 111 need to add
 112
 113     memmap=66M$0x3be00000
 114
 115 as parameter to the command line of the virtual machine's kernel. Reboot the
 116 guest and load jailhouse.ko. Then enable Jailhouse like this:
 117
 118     jailhouse enable /path/to/qemu-vm.cell
 119
 120 Next you can create a cell with a demonstration application as follows:
 121
 122     jailhouse cell create /path/to/apic-demo.cell
 123     jailhouse cell load apic-demo /path/to/apic-demo.bin -a 0xf0000
 124     jailhouse cell start apic-demo
 125
 126 apic-demo.bin is left by the built process in the inmates/ directory. This
 127 application will program the APIC timer interrupt to fire at 10 Hz, measuring
 128 the jitter against the PM timer and displaying the result on the
 129 console. Given that this demonstration runs in a virtual machine, obviously
 130 no decent latencies should be expected.
 131
 132 To demonstrate the execution of a second, non-Linux cell, issue the following
 133 commands:
 134
 135     jailhouse cell create /path/to/tiny-demo.cell
 136     jailhouse cell load tiny-demo /path/to/tiny-demo.bin -a 0xf0000
 137     jailhouse cell start tiny-demo
 138
 139 The tiny-demo will use the second serial port provided by QEMU. You will find
 140 its output in a virtual console of the QEMU window.
 141
 142 After creation, cells are addressed via the command line tool by providing
 143 their names or their runtime-assigned IDs. You can obtain information about
 144 active cells this way:
 145
 146     jailhouse cell list
 147
 148 Cell destruction is performed by specifying the configuration file of the
 149 desired cell. This command will destroy the apic-demo:
 150
 151     jailhouse cell destroy apic-demo
 152
 153 Note that the first destruction or shutdown request on the apic-demo cell will
 154 fail. The reason is that this cell contains logic to demonstrate an ordered
 155 shutdown as well as the ability of a cell to reject shutdown requests.
 156
 157 The apic-demo cell has another special property for demonstration purposes: As
 158 long as it is running, no cell reconfigurations can be performed - the
 159 apic-demo locks the hypervisor in this regard. In order to destroy another cell
 160 or create an additional one, shut down the apic-demo first.
 161
 162 While cell configurations are locked, it is still possible, though, to reload
 163 the content of existing cell (provided they accept their shutdown first). To
 164 reload and restart the tiny-demo, issue the following commands:
 165
 166     jailhouse cell load tiny-demo /path/to/tiny-demo.bin -a 0xf0000
 167     jailhouse cell start tiny-demo
 168
 169 Finally, Jailhouse is can be stopped completely again:
 170
 171     jailhouse disable
 172
 173 All non-Linux cells running at that point will be destroyed, and resources
 174 will be returned to Linux.