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.
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.
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.
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.
33 - https://github.com/siemens/jailhouse
37 - https://github.com/siemens/jailhouse.git
38 - git@github.com:siemens/jailhouse.git
40 Frequently Asked Questions (FAQ):
42 - See [FAQ file](FAQ.md)
46 - jailhouse-dev@googlegroups.com
49 - jailhouse-dev+subscribe@googlegroups.com
50 - https://groups.google.com/forum/#!forum/jailhouse-dev/join
53 - http://news.gmane.org/gmane.linux.jailhouse
55 Continuous integration:
57 - https://travis-ci.org/siemens/jailhouse
60 - ![](https://travis-ci.org/siemens/jailhouse.svg?branch=master) on master
61 - ![](https://travis-ci.org/siemens/jailhouse.svg?branch=next) on next
65 - https://scan.coverity.com/projects/4114
68 - ![](https://scan.coverity.com/projects/4114/badge.svg) on coverity_scan
70 See the [contribution documentation](CONTRIBUTING.md) for details
71 on how to write Jailhouse patches and propose them for upstream integration.
74 Requirements (preliminary)
75 --------------------------
81 - support for 64-bit and VMX, more precisely
82 - EPT (extended page tables)
83 - unrestricted guest mode
86 - Intel IOMMU (VT-d) with interrupt remapping support
87 (except when running inside QEMU)
91 - support for 64-bit and SVM (AMD-V), and also
92 - NPT (nested page tables); required
93 - Decode Assists; recommended
95 - AMD IOMMU (AMD-Vi) is unsupported now but will be required in future
97 - at least 2 logical CPUs
99 - x86-64 Linux kernel (tested against >= 3.14)
101 - VT-d IOMMU usage (DMAR) has to be disabled in the Linux kernel, e.g. via
102 the command line parameter:
106 - To exploit the faster x2APIC, interrupt remapping needs to be on in the
107 kernel (check for CONFIG_IRQ_REMAP)
113 - ARMv7 with virtualization extensions
115 - Appropriate boot loader support (typically U-Boot)
116 - Linux is started in HYP mode
117 - PSCI support for CPU offlining
119 - at least 2 logical CPUs
123 - Banana Pi (see also [below](#setup-on-banana-pi-arm-board))
127 - ARM Versatile Express with Cortex-A15 or A7 cores
128 (includes ARM Fast Model)
134 Simply run make, optionally specifying the target kernel directory:
136 make [KDIR=/path/to/kernel/objects]
138 Except for the hypervisor image `jailhouse*.bin` that has to be available in the
139 firmware search path (invoke `make firmware_install` for this), you can run
140 Jailhouse from the build directory. Alternatively, install everything on the
141 target machine by calling `make install` from the top-level directory.
147 Jailhouse requires one configuration file for the complete system and one for
148 each additional cell beside Linux. The configuration is currently being
149 defined manually by filling C structures. To study the structure, use
150 configs/qemu-vm.c for a system configuration and configs/apic-demo.c for a cell
151 configuration as reference. The build system will pick up every .c file from
152 the configs/ directory and generate a corresponding .cell file. .cell files can
153 then be passed to the jailhouse command line tool for enabling the hypervisor
154 and creating new cells.
157 Demonstration in QEMU/KVM
158 -------------------------
160 The included system configuration qemu-vm.c can be used to run Jailhouse in
161 QEMU/KVM virtual machine on x86 hosts (Intel and AMD are supported). Currently
162 it requires Linux 3.18 or newer on the host side (Intel is fine with 3.17).
163 QEMU is required in a recent version (2.1) as well if you want to use the
164 configuration file included in the source tree.
166 You also need a Linux guest image with a recent kernel (tested with >= 3.9) and
167 the ability to build a module for this kernel. Further steps depend on the type
168 of CPU you have on your system.
170 For Intel CPUs: Make sure the kvm-intel module was loaded with nested=1 to
171 enable nested VMX support. Start the virtual machine as follows:
173 qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
174 -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx,+x2apic \
175 -drive file=LinuxInstallation.img,id=disk,if=none \
176 -device ide-hd,drive=disk -serial stdio -serial vc \
177 -device intel-hda,addr=1b.0 -device hda-duplex
179 For AMD CPUs: Make sure the kvm-amd module was loaded with nested=1 to enable
180 nested SVM support. Start the virtual machine as follows:
182 qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
183 -cpu host,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+svm,+x2apic \
184 -drive file=LinuxInstallation.img,id=disk,if=none \
185 -device ide-hd,drive=disk -serial stdio -serial vc \
186 -device intel-hda,addr=1b.0 -device hda-duplex
188 Inside the VM, make sure that jailhouse-*.bin, generated by the build process,
189 are available for firmware loading (typically /lib/firmware), see above for
192 The hypervisor requires a contiguous piece of RAM for itself and each
193 additional cell. This currently has to be pre-allocated during boot-up. So you
196 memmap=66M$0x3b000000
198 as parameter to the command line of the virtual machine's kernel. Reboot the
199 guest and load jailhouse.ko. Then enable Jailhouse like this:
201 jailhouse enable /path/to/qemu-vm.cell
203 Next you can create a cell with a demonstration application as follows:
205 jailhouse cell create /path/to/apic-demo.cell
206 jailhouse cell load apic-demo /path/to/apic-demo.bin -a 0xf0000
207 jailhouse cell start apic-demo
209 apic-demo.bin is left by the built process in the inmates/demos/x86 directory.
210 This application will program the APIC timer interrupt to fire at 10 Hz,
211 measuring the jitter against the PM timer and displaying the result on the
212 console. Given that this demonstration runs in a virtual machine, obviously
213 no decent latencies should be expected.
215 After creation, cells are addressed via the command line tool by providing
216 their names or their runtime-assigned IDs. You can obtain information about
217 active cells this way:
221 Cell destruction is performed by specifying the configuration file of the
222 desired cell. This command will destroy the apic-demo:
224 jailhouse cell destroy apic-demo
226 Note that the first destruction or shutdown request on the apic-demo cell will
227 fail. The reason is that this cell contains logic to demonstrate an ordered
228 shutdown as well as the ability of a cell to reject shutdown requests.
230 The apic-demo cell has another special property for demonstration purposes: As
231 long as it is running, no cell reconfigurations can be performed - the
232 apic-demo locks the hypervisor in this regard. In order to destroy another cell
233 or create an additional one, shut down the apic-demo first.
235 jailhouse cell shutdown apic-demo # call again if error is returned
237 To demonstrate the execution of a second, non-Linux cell, issue the following
240 jailhouse cell create /path/to/pci-demo.cell
241 jailhouse cell load pci-demo /path/to/pci-demo.bin -a 0xf0000
242 jailhouse cell start pci-demo
244 The pci-demo will use the second serial port provided by QEMU. You will find
245 its output in a virtual console of the QEMU window. The purpose of this demo is
246 to show basic PCI device configuration and MSI handling.
248 While cell configurations are locked, it is still possible, though, to reload
249 the content of existing cell (provided they accept their shutdown first). To
250 reload and restart the tiny-demo, issue the following commands:
252 jailhouse cell start apic-demo
253 jailhouse cell load pci-demo /path/to/pci-demo.bin -a 0xf0000
254 jailhouse cell start pci-demo
256 Finally, Jailhouse is can be stopped completely again:
258 jailhouse disable # call again on error due to running apic-demo
260 All non-Linux cells running at that point will be destroyed, and resources
261 will be returned to Linux.
264 Setup on Banana Pi ARM board
265 ----------------------------
267 The Banana Pi is a cheap Raspberry-Pi-like ARM board with an Allwinner A20 SoC
268 (dual-core Cortex-A7). It runs mainline Linux kernels and U-Boot and is
269 comparably well hackable. Further information can be found on
270 http://linux-sunxi.org.
272 For Jailhouse, a U-Boot (pre-)release more recent than v2015.04-rc1 is
273 required. Tested and know to work is git revision bd2a4888b1.
275 The Linux kernel version should be at least 3.19-rcX. The configuration used
276 for continuous integration builds can serve as reference, see
277 `ci/kernel-config-banana-pi`. The kernel has to be booted with the following
278 additional parameters, e.g. by adjusting the U-Boot environment accordingly:
280 mem=958M vmalloc=512M
282 The recommended cross-toolchain is available from Linaro, see
283 http://www.linaro.org/downloads.
285 Before building Jailhouse, copy the configuration header file
286 `ci/jailhouse-config-banana-pi.h` to `hypervisor/include/jailhouse/config.h`.
289 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
290 KDIR=/path/to/arm-kernel/objects
292 Binaries can be installed directly to the target root file system if it is
295 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
296 KDIR=/path/to/arm-kernel/objects DESTDIR=/mount-point install
298 Cell configurations and demo inmates will not be installed this way and have to
299 be transferred manually as needed. Make sure you have `configs/bananapi.cell`
300 and, as desired, the inmates configs (`configs/bananapi-*.cell`) and binaries
301 (`inmates/demos/arm/*.bin`) available on the target.
303 Jailhouse and inmates are started on ARM just like on x86. The only difference
304 is that inmates have to be loaded at offset 0. Just leave out the `-a`
305 parameter when invoking `jailhouse cell load`.