dimension. Use at your own risk. And keep the reset button in reach.
-Community
----------
+Community Resources
+-------------------
Project home:
- https://github.com/siemens/jailhouse.git
- git@github.com:siemens/jailhouse.git
+Frequently Asked Questions (FAQ):
+
+ - See [FAQ file](FAQ.md)
+
Mailing list:
- jailhouse-dev@googlegroups.com
- Archives
- http://news.gmane.org/gmane.linux.jailhouse
+Continuous integration:
+
+ - https://travis-ci.org/siemens/jailhouse
+
+ - Status:
+ -  on master
+ -  on next
+
+Static code analysis:
+
+ - https://scan.coverity.com/projects/4114
+
+ - Status:
+ -  on coverity_scan
+
+See the [contribution documentation](CONTRIBUTING.md) for details
+on how to write Jailhouse patches and propose them for upstream integration.
+
Requirements (preliminary)
--------------------------
- at least 2 logical CPUs
- x86-64 Linux kernel (tested against >= 3.14)
+
- VT-d IOMMU usage (DMAR) has to be disabled in the Linux kernel, e.g. via
the command line parameter:
- To exploit the faster x2APIC, interrupt remapping needs to be on in the
kernel (check for CONFIG_IRQ_REMAP)
+ARM architecture:
+
+ - Abstract:
+
+ - ARMv7 with virtualization extensions
+
+ - Appropriate boot loader support (typically U-Boot)
+ - Linux is started in HYP mode
+ - PSCI support for CPU offlining
+
+ - at least 2 logical CPUs
+
+ - Board support:
+
+ - Banana Pi ([see more](Documentation/setup-on-banana-pi-arm-board.md))
+
+ - NVIDIA Jetson TK1
+
+ - ARM Versatile Express with Cortex-A15 or A7 cores
+ (includes ARM Fast Model)
+
+On x86, hardware capabilities can be validated by running
+
+ jailhouse hardware check sysconfig.cell
+
+using the binary system configuration created for the target (see
+[below](#configuration)).
+
Build & Installation
--------------------
-------------
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
-configs/qemu-vm.c for a system configuration and configs/apic-demo.c for a cell
-configuration as reference. The build system will pick up every .c file from
-the configs/ 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.
+each additional cell besides the primary Linux. These .cell files have to be
+passed to the jailhouse command line tool for enabling the hypervisor or
+creating new cells.
+
+A system configuration can be created on the target system by running the
+following command:
+
+ jailhouse config create sysconfig.c
+
+In order to translate this into the required binary form, place this file in
+the configs/ directory. The build system will pick up every .c file from there
+and generate a corresponding .cell file.
+
+Depending on the target system, the C structures may require some adjustments to
+make Jailhouse work properly or to reduce the desired access rights of the Linux
+root cell.
+
+Configurations for additional (non-root) cells currently require manual
+creation. To study the structures, use one of the demo cell configurations files
+as reference, e.g. configs/apic-demo.c or configs/e1000-demo.c.
Demonstration in QEMU/KVM
enable nested VMX support. Start the virtual machine as follows:
qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
- -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx,+x2apic \
- -drive file=LinuxInstallation.img,id=disk,if=none \
+ -cpu kvm64,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+vmx \
+ -drive file=LinuxInstallation.img,format=raw|qcow2|...,id=disk,if=none \
-device ide-hd,drive=disk -serial stdio -serial vc \
-device intel-hda,addr=1b.0 -device hda-duplex
nested SVM support. Start the virtual machine as follows:
qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \
- -cpu host,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock,+svm,+x2apic \
- -drive file=LinuxInstallation.img,id=disk,if=none \
+ -cpu host,-kvm_pv_eoi,-kvm_steal_time,-kvm_asyncpf,-kvmclock \
+ -drive file=LinuxInstallation.img,format=raw|qcow2|...,id=disk,if=none \
-device ide-hd,drive=disk -serial stdio -serial vc \
-device intel-hda,addr=1b.0 -device hda-duplex
-Inside the VM, make sure that jailhouse-*.bin, generated by the build process,
+Inside the VM, make sure that `jailhouse-*.bin`, generated by the build process,
are available for firmware loading (typically /lib/firmware), see above for
installation steps.
memmap=66M$0x3b000000
-as parameter to the command line of the virtual machine's kernel. Reboot the
-guest and load jailhouse.ko. Then enable Jailhouse like this:
+as parameter to the command line of the virtual machine's kernel. The Jailhouse
+QEMU cell config will block use of the serial port by the guest OS, so make
+sure that the guest kernel command line does NOT have its console set to log
+to the serial port (ie remove any 'console=ttyS0' arguments from the grub
+config). Reboot the guest and load jailhouse.ko. Then enable Jailhouse like
+this:
jailhouse enable /path/to/qemu-vm.cell
All non-Linux cells running at that point will be destroyed, and resources
will be returned to Linux.
-
-
-Setup on Banana Pi ARM board
-----------------------------
-
-The Banana Pi is a cheap Raspberry-Pi-like ARM board with an Allwinner A20 SoC
-(dual-core Cortex-A7). It runs mainline Linux kernels and U-Boot and is
-comparably well hackable. Further information can be found on
-http://linux-sunxi.org.
-
-For Jailhouse, U-Boot currently requires a few additional patches that can be
-retrieved from https://github.com/siemens/u-boot/commits/sunxi.
-
-The Linux kernel version should be at least 3.19-rcX. The configuration used
-for continuous integration builds can serve as reference, see
-`ci/kernel-config-banana-pi`. The kernel has to be booted with the following
-additional parameters, e.g. by adjusting the U-Boot environment accordingly:
-
- mem=958M vmalloc=512M
-
-The recommended cross-toolchain is available from Linaro, see
-http://www.linaro.org/downloads.
-
-Before building Jailhouse, copy the configuration header file
-`ci/jailhouse-config-banana-pi.h` to `hypervisor/include/jailhouse/config.h`.
-Then run make:
-
- make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
- KDIR=/path/to/arm-kernel/objects
-
-Binaries can be installed directly to the target root file system if it is
-mounted on the host:
-
- make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- \
- KDIR=/path/to/arm-kernel/objects DESTDIR=/mount-point install
-
-Cell configurations and demo inmates will not be installed this way and have to
-be transferred manually as needed. Make sure you have `configs/bananapi.cell`
-and, as desired, the inmates configs (`configs/bananapi-*.cell`) and binaries
-(`inmates/demos/arm/*.bin`) available on the target.
-
-Jailhouse and inmates are started on ARM just like on x86. The only difference
-is that inmates have to be loaded at offset 0. Just leave out the `-a`
-parameter when invoking `jailhouse cell load`.
projects / jailhouse.git / blobdiff