README.md

   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:
  32
  33  - https://github.com/siemens/jailhouse
  34
  35 Source code:
  36
  37  - https://github.com/siemens/jailhouse.git
  38  - git@github.com:siemens/jailhouse.git
  39
  40 Mailing list:
  41
  42   - jailhouse-dev@googlegroups.com
  43
  44   - Subscription:
  45     - jailhouse-dev+subscribe@googlegroups.com
  46     - https://groups.google.com/forum/#!forum/jailhouse-dev/join
  47
  48   - Archives
  49     - http://news.gmane.org/gmane.linux.jailhouse
  50
  51 Continuous Integration:
  52
  53   - https://travis-ci.org/siemens/jailhouse
  54
  55   - Status:
  56     - ![](https://travis-ci.org/siemens/jailhouse.svg?branch=master) on master
  57     - ![](https://travis-ci.org/siemens/jailhouse.svg?branch=next) on next
  58
  59 See the [contribution documentation](CONTRIBUTING.md) for details
  60 on how to write Jailhouse patches and propose them for upstream integration.
  61
  62
  63 Requirements (preliminary)
  64 --------------------------
  65
  66 x86 architecture:
  67
  68   - Intel system:
  69
  70     - support for 64-bit and VMX, more precisely
  71       - EPT (extended page tables)
  72       - unrestricted guest mode
  73       - preemption timer
  74
  75     - Intel IOMMU (VT-d) with interrupt remapping support
  76       (except when running inside QEMU)
  77
  78   - or AMD system:
  79
  80     - support for 64-bit and SVM (AMD-V), and also
  81       - NPT (nested page tables); required
  82       - Decode Assists; recommended
  83
  84     - AMD IOMMU (AMD-Vi) is unsupported now but will be required in future
  85
  86   - at least 2 logical CPUs
  87
  88   - x86-64 Linux kernel (tested against >= 3.14)
  89     - VT-d IOMMU usage (DMAR) has to be disabled in the Linux kernel, e.g. via
  90       the command line parameter:
  91
  92           intel_iommu=off
  93
  94     - To exploit the faster x2APIC, interrupt remapping needs to be on in the
  95       kernel (check for CONFIG_IRQ_REMAP)
  96
  97
  98 Build & Installation
  99 --------------------
 100
 101 Simply run make, optionally specifying the target kernel directory:
 102
 103     make [KDIR=/path/to/kernel/objects]
 104
 105 Except for the hypervisor image `jailhouse*.bin` that has to be available in the
 106 firmware search path (invoke `make firmware_install` for this), you can run
 107 Jailhouse from the build directory. Alternatively, install everything on the
 108 target machine by calling `make install` from the top-level directory.
 109
 110
 111 Configuration
 112 -------------
 113
 114 Jailhouse requires one configuration file for the complete system and one for
 115 each additional cell beside Linux. The configuration is currently being
 116 defined manually by filling C structures. To study the structure, use
 117 configs/qemu-vm.c for a system configuration and configs/apic-demo.c for a cell
 118 configuration as reference. The build system will pick up every .c file from
 119 the configs/ directory and generate a corresponding .cell file. .cell files can
 120 then be passed to the jailhouse command line tool for enabling the hypervisor
 121 and creating new cells.
 122
 123
 124 Demonstration in QEMU/KVM
 125 -------------------------
 126
 127 The included system configuration qemu-vm.c can be used to run Jailhouse in
 128 QEMU/KVM virtual machine on x86 hosts (Intel and AMD are supported). Currently
 129 it requires Linux 3.18 or newer on the host side (Intel is fine with 3.17).
 130 QEMU is required in a recent version (2.1) as well if you want to use the
 131 configuration file included in the source tree.
 132
 133 You also need a Linux guest image with a recent kernel (tested with >= 3.9) and
 134 the ability to build a module for this kernel. Further steps depend on the type
 135 of CPU you have on your system.
 136
 137 For Intel CPUs: Make sure the kvm-intel module was loaded with nested=1 to
 138 enable nested VMX support. Start the virtual machine as follows:
 139
 140     qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
 141         -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx,+x2apic \
 142         -drive file=LinuxInstallation.img,id=disk,if=none \
 143         -device ide-hd,drive=disk -serial stdio -serial vc \
 144         -device intel-hda,addr=1b.0 -device hda-duplex
 145
 146 For AMD CPUs: Make sure the kvm-amd module was loaded with nested=1 to enable
 147 nested SVM support. Start the virtual machine as follows:
 148
 149     qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
 150         -cpu host,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+svm,+x2apic \
 151         -drive file=LinuxInstallation.img,id=disk,if=none \
 152         -device ide-hd,drive=disk -serial stdio -serial vc \
 153         -device intel-hda,addr=1b.0 -device hda-duplex
 154
 155 Inside the VM, make sure that jailhouse-*.bin, generated by the build process,
 156 are available for firmware loading (typically /lib/firmware), see above for
 157 installation steps.
 158
 159 The hypervisor requires a contiguous piece of RAM for itself and each
 160 additional cell. This currently has to be pre-allocated during boot-up. So you
 161 need to add
 162
 163     memmap=66M$0x3b000000
 164
 165 as parameter to the command line of the virtual machine's kernel. Reboot the
 166 guest and load jailhouse.ko. Then enable Jailhouse like this:
 167
 168     jailhouse enable /path/to/qemu-vm.cell
 169
 170 Next you can create a cell with a demonstration application as follows:
 171
 172     jailhouse cell create /path/to/apic-demo.cell
 173     jailhouse cell load apic-demo /path/to/apic-demo.bin -a 0xf0000
 174     jailhouse cell start apic-demo
 175
 176 apic-demo.bin is left by the built process in the inmates/demos/x86 directory.
 177 This application will program the APIC timer interrupt to fire at 10 Hz,
 178 measuring the jitter against the PM timer and displaying the result on the
 179 console. Given that this demonstration runs in a virtual machine, obviously
 180 no decent latencies should be expected.
 181
 182 After creation, cells are addressed via the command line tool by providing
 183 their names or their runtime-assigned IDs. You can obtain information about
 184 active cells this way:
 185
 186     jailhouse cell list
 187
 188 Cell destruction is performed by specifying the configuration file of the
 189 desired cell. This command will destroy the apic-demo:
 190
 191     jailhouse cell destroy apic-demo
 192
 193 Note that the first destruction or shutdown request on the apic-demo cell will
 194 fail. The reason is that this cell contains logic to demonstrate an ordered
 195 shutdown as well as the ability of a cell to reject shutdown requests.
 196
 197 The apic-demo cell has another special property for demonstration purposes: As
 198 long as it is running, no cell reconfigurations can be performed - the
 199 apic-demo locks the hypervisor in this regard. In order to destroy another cell
 200 or create an additional one, shut down the apic-demo first.
 201
 202     jailhouse cell shutdown apic-demo  # call again if error is returned
 203
 204 To demonstrate the execution of a second, non-Linux cell, issue the following
 205 commands:
 206
 207     jailhouse cell create /path/to/pci-demo.cell
 208     jailhouse cell load pci-demo /path/to/pci-demo.bin -a 0xf0000
 209     jailhouse cell start pci-demo
 210
 211 The pci-demo will use the second serial port provided by QEMU. You will find
 212 its output in a virtual console of the QEMU window. The purpose of this demo is
 213 to show basic PCI device configuration and MSI handling.
 214
 215 While cell configurations are locked, it is still possible, though, to reload
 216 the content of existing cell (provided they accept their shutdown first). To
 217 reload and restart the tiny-demo, issue the following commands:
 218
 219     jailhouse cell start apic-demo
 220     jailhouse cell load pci-demo /path/to/pci-demo.bin -a 0xf0000
 221     jailhouse cell start pci-demo
 222
 223 Finally, Jailhouse is can be stopped completely again:
 224
 225     jailhouse disable  # call again on error due to running apic-demo
 226
 227 All non-Linux cells running at that point will be destroyed, and resources
 228 will be returned to Linux.
 229
 230
 231 Setup on Banana Pi ARM board
 232 ----------------------------
 233
 234 The Banana Pi is a cheap Raspberry-Pi-like ARM board with an Allwinner A20 SoC
 235 (dual-core Cortex-A7). It runs mainline Linux kernels and U-Boot and is
 236 comparably well hackable. Further information can be found on
 237 http://linux-sunxi.org.
 238
 239 For Jailhouse, U-Boot currently requires a few additional patches that can be
 240 retrieved from https://github.com/siemens/u-boot/commits/sunxi.
 241
 242 The Linux kernel version should be at least 3.19-rcX. The configuration used
 243 for continuous integration builds can serve as reference, see
 244 `ci/kernel-config-banana-pi`. The kernel has to be booted with the following
 245 additional parameters, e.g. by adjusting the U-Boot environment accordingly:
 246
 247     mem=958M vmalloc=512M
 248
 249 The recommended cross-toolchain is available from Linaro, see
 250 http://www.linaro.org/downloads.
 251
 252 Before building Jailhouse, copy the configuration header file
 253 `ci/jailhouse-config-banana-pi.h` to `hypervisor/include/jailhouse/config.h`.
 254 Then run make:
 255
 256     make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
 257          KDIR=/path/to/arm-kernel/objects
 258
 259 Binaries can be installed directly to the target root file system if it is
 260 mounted on the host:
 261
 262     make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
 263          KDIR=/path/to/arm-kernel/objects DESTDIR=/mount-point install
 264
 265 Cell configurations and demo inmates will not be installed this way and have to
 266 be transferred manually as needed. Make sure you have `configs/bananapi.cell`
 267 and, as desired, the inmates configs (`configs/bananapi-*.cell`) and binaries
 268 (`inmates/demos/arm/*.bin`) available on the target.
 269
 270 Jailhouse and inmates are started on ARM just like on x86. The only difference
 271 is that inmates have to be loaded at offset 0. Just leave out the `-a`
 272 parameter when invoking `jailhouse cell load`.