{"id":13508378,"url":"https://github.com/siemens/jailhouse","last_synced_at":"2025-04-14T08:16:40.998Z","repository":{"id":11304493,"uuid":"13720762","full_name":"siemens/jailhouse","owner":"siemens","description":"Linux-based partitioning hypervisor","archived":false,"fork":false,"pushed_at":"2024-05-18T14:16:54.000Z","size":5555,"stargazers_count":1792,"open_issues_count":0,"forks_count":337,"subscribers_count":156,"default_branch":"master","last_synced_at":"2025-04-14T08:16:29.055Z","etag":null,"topics":["hypervisor","linux","real-time"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siemens.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-20T14:47:41.000Z","updated_at":"2025-04-14T02:18:37.000Z","dependencies_parsed_at":"2023-02-10T05:45:16.387Z","dependency_job_id":"e68f4ab9-e5e0-466e-ad7c-05f1520e5069","html_url":"https://github.com/siemens/jailhouse","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siemens%2Fjailhouse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siemens%2Fjailhouse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siemens%2Fjailhouse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siemens%2Fjailhouse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siemens","download_url":"https://codeload.github.com/siemens/jailhouse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248844000,"owners_count":21170499,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hypervisor","linux","real-time"],"created_at":"2024-08-01T02:00:52.254Z","updated_at":"2025-04-14T08:16:40.953Z","avatar_url":"https://github.com/siemens.png","language":"C","funding_links":[],"categories":["Research Projects","C","Operation System","linux","Hypervisors","System"],"sub_categories":["AMD","Embedded Operation System","Container Runtime Distributions","Embedded Operation Systems"],"readme":"JAILHOUSE\n=========\n\nIntroduction\n------------\n\nJailhouse is a partitioning Hypervisor based on Linux. It is able to run\nbare-metal applications or (adapted) operating systems besides Linux. For this\npurpose, it configures CPU and device virtualization features of the hardware\nplatform in a way that none of these domains, called \"cells\" here, can\ninterfere with each other in an unacceptable way.\n\nJailhouse is optimized for simplicity rather than feature richness. Unlike\nfull-featured Linux-based hypervisors like KVM or Xen, Jailhouse does not\nsupport overcommitment of resources like CPUs, RAM or devices. It performs no\nscheduling and only virtualizes those resources in software, that are essential\nfor a platform and cannot be partitioned in hardware.\n\nOnce Jailhouse is activated, it runs bare-metal, i.e. it takes full control\nover the hardware and needs no external support. However, in contrast to other\nbare-metal hypervisors, it is loaded and configured by a normal Linux system.\nIts management interface is based on Linux infrastructure. So you boot Linux\nfirst, then you enable Jailhouse and finally you split off parts of the\nsystem's resources and assign them to additional cells.\n\nCommunity Resources\n-------------------\n\nProject home:\n\n - https://github.com/siemens/jailhouse\n\nSource code:\n\n - https://github.com/siemens/jailhouse.git\n - git@github.com:siemens/jailhouse.git\n\nDemo and testing images:\n\n - https://github.com/siemens/jailhouse-images\n\nFrequently Asked Questions (FAQ):\n\n - See [FAQ file](FAQ.md)\n\nIRC channel:\n  - Freenode, irc.freenode.net, #jailhouse\n  - [![Webchat](https://img.shields.io/badge/irc-freenode-blue.svg \"IRC Freenode\")](https://webchat.freenode.net/?channels=jailhouse)\n\nMailing list:\n\n  - jailhouse-dev@googlegroups.com\n\n  - Subscription:\n    - jailhouse-dev+subscribe@googlegroups.com\n    - https://groups.google.com/forum/#!forum/jailhouse-dev/join\n\n  - Archives\n    - https://groups.google.com/forum/#!forum/jailhouse-dev\n    - https://www.mail-archive.com/jailhouse-dev@googlegroups.com\n\nContinuous integration:\n\n  - https://github.com/siemens/jailhouse/actions\n\n  - Status:\n    - ![](https://github.com/siemens/jailhouse/actions/workflows/main.yaml/badge.svg?branch=master) on master\n    - ![](https://github.com/siemens/jailhouse/actions/workflows/main.yaml/badge.svg?branch=next) on next\n\nStatic code analysis:\n\n  - https://scan.coverity.com/projects/siemens-jailhouse\n\n  - Status:\n    - ![](https://scan.coverity.com/projects/siemens-jailhouse/badge.svg) on coverity_scan\n\nSee the [contribution documentation](CONTRIBUTING.md) for details\non how to write Jailhouse patches and propose them for upstream integration.\n\n\nHardware requirements (preliminary)\n-----------------------------------\n\n#### x86 architecture:\n\n  - Intel system:\n\n    - support for 64-bit and VMX, more precisely\n      - EPT (extended page tables)\n      - unrestricted guest mode\n      - preemption timer\n\n    - Intel IOMMU (VT-d) with interrupt remapping support\n      (except when running inside QEMU)\n\n  - or AMD system:\n\n    - support for 64-bit and SVM (AMD-V), and also\n      - NPT (nested page tables); required\n      - Decode Assists; recommended\n\n    - AMD IOMMU (AMD-Vi) is unsupported now but will be required in future\n\n  - At least 2 logical CPUs\n\n#### ARM architecture:\n\n  - ARMv7 with virtualization extensions or ARMv8\n\n  - At least 2 logical CPUs\n\n  - Supported ARM boards:\n\n    - Banana Pi ([see more](Documentation/setup-on-banana-pi-arm-board.md))\n\n    - Orange Pi Zero (256 MB version)\n\n    - NVIDIA Jetson TK1\n\n    - ARM Versatile Express with Cortex-A15 or A7 cores\n      (includes ARM Fast Model)\n\n    - emtrion emCON-RZ/G1x series based on Renesas RZ/G ([see more](Documentation/setup-on-emtrion-emcon-rz-boards.md))\n\n  - Supported ARM64 boards:\n\n    - AMD Seattle / SoftIron Overdrive 3000\n\n    - LeMaker HiKey\n\n    - NVIDIA Jetson TX1 and TX2\n\n    - Xilinx ZCU102 (ZynqMP evaluation board)\n\n    - NXP MCIMX8M-EVK\n\n\nSoftware requirements\n---------------------\n\n#### x86 architecture:\n\n  - x86-64 Linux kernel (tested against 3.14+)\n\n    - VT-d IOMMU usage (DMAR) has to be disabled in the Linux kernel, e.g. via\n      the command line parameter:\n\n          intel_iommu=off\n\n    - To exploit the faster x2APIC, interrupt remapping needs to be on in the\n      kernel (check for CONFIG_IRQ_REMAP)\n\n  - The hypervisor requires a contiguous piece of RAM for itself and each\n    additional cell. This currently has to be pre-allocated during boot-up.\n    On x86 this is typically done by adding\n\n        memmap=82M$0x3a000000\n\n    as parameter to the command line of the virtual machine's kernel. Note that\n    if you plan to put this parameter in GRUB2 variables in /etc/default/grub,\n    then you will need three escape characters before the dollar\n    (e.g. ```GRUB_CMDLINE_LINUX_DEFAULT=\"memmap=82M\\\\\\$0x3a000000\"```).\n\n#### ARM architecture:\n\n  - Linux kernel:\n    - 3.19+ for ARM\n    - 4.7+ for ARM64\n\n  - Appropriate boot loader support (typically U-Boot)\n     - Linux is started in HYP mode\n     - PSCI support for CPU offlining\n\n  - The hypervisor requires a contiguous piece of RAM for itself and each\n    additional cell. This currently has to be pre-allocated during boot-up.\n    On ARM this can be obtained by reducing the amount of memory seen by the\n    kernel (through the `mem=` kernel boot parameter) or by modifying the\n    Device Tree (i.e. the `reserved-memory` node).\n\n\nBuild \u0026 Installation\n--------------------\n\nSimply run `make`, optionally specifying the target kernel directory:\n\n    make [KDIR=/path/to/kernel/objects]\n\n\n#### Installation\n\nIt is recommended to install all of Jailhouse on your target machine. That will\ntake care of a kernel module, the firmware, tools etc. Just call\n\n    make install\n\nfrom the top-level directory.\n\nThe traditional Linux cross-compilation (i.e. `ARCH=` and `CROSS_COMPILE=`) and\ninstallation (i.e. `DESTDIR=`) flags are supported as well.\n\n#### Running without Installation\n\nExcept for the hypervisor image `jailhouse*.bin`, that has to be available in\nthe firmware search path, you can run Jailhouse from the build directory.\nIf you cannot or do not want to use `make install`, you can either install just\nthe firmware using `make firmware_install` or customize the firmware search\npath:\n\n    echo -n /path/to/jailhouse/hypervisor/ \\\n        \u003e /sys/module/firmware_class/parameters/path\n\n\nConfiguration\n-------------\n\nJailhouse requires one configuration file for the complete system and one for\neach additional cell besides the primary Linux. These .cell files have to be\npassed to the jailhouse command line tool for enabling the hypervisor or\ncreating new cells.\n\nOn x86, the required hardware capabilities can be validated by running\n\n    jailhouse hardware check\n\nA system configuration can be created on an x86 target system by running the\nfollowing command:\n\n    jailhouse config create sysconfig.c\n\nIn order to translate this into the required binary form, place this file in\nthe configs/x86/ directory. The build system will pick up every .c file from\nthere and generate a corresponding .cell file.\n\nCurrently, there is no config generator for the ARM architecture; therefore the\nconfig file must be manually written by starting from the reference examples\nand checking hardware-specific datasheets, DTS and /proc entries.\n\nDepending on the target system, the C structures may require some adjustments to\nmake Jailhouse work properly or to reduce the desired access rights of the Linux\nroot cell.\n\nConfigurations for additional (non-root) cells currently require manual\ncreation. To study the structures, use one of the demo cell configurations files\nas reference, e.g. configs/x86/apic-demo.c or configs/x86/e1000-demo.c.\n\n\nx86 Demonstration in QEMU/KVM\n-----------------------------\n\n**NOTE**: You can also build and execute the following demo steps with the\nhelp of the jailhouse-images side project at\nhttps://github.com/siemens/jailhouse-images.\n\nThe included system configuration qemu-x86.c can be used to run Jailhouse in\nQEMU/KVM virtual machine on x86 hosts (Intel and AMD are supported). Currently\nit requires Linux 4.4 or newer on the host side. QEMU version 2.8 or newer is\nrequired.\n\nYou also need a Linux guest image with a recent kernel (tested with \u003e= 3.9) and\nthe ability to build a module for this kernel. Further steps depend on the type\nof CPU you have on your system.\n\nFor Intel CPUs: Make sure the kvm-intel module was loaded with nested=1 to\nenable nested VMX support. Start the virtual machine as follows:\n\n    qemu-system-x86_64 -machine q35,kernel_irqchip=split -m 1G -enable-kvm \\\n        -smp 4 -device intel-iommu,intremap=on,x-buggy-eim=on \\\n        -cpu host,-kvm-pv-eoi,-kvm-pv-ipi,-kvm-asyncpf,-kvm-steal-time,-kvmclock \\\n        -drive file=LinuxInstallation.img,format=raw|qcow2|...,id=disk,if=none \\\n        -device ide-hd,drive=disk -serial stdio -serial vc \\\n        -netdev user,id=net -device e1000e,addr=2.0,netdev=net \\\n        -device intel-hda,addr=1b.0 -device hda-duplex -device pcie-pci-bridge\n\nFor AMD CPUs: Make sure the kvm-amd module was loaded with nested=1 to enable\nnested SVM support. Start the virtual machine as follows:\n\n    qemu-system-x86_64 -machine q35 -m 1G -enable-kvm -smp 4 \\\n        -cpu host,-kvm-pv-eoi,-kvm-pv-ipi,-kvm-asyncpf,-kvm-steal-time,-kvmclock \\\n        -drive file=LinuxInstallation.img,format=raw|qcow2|...,id=disk,if=none \\\n        -device ide-hd,drive=disk -serial stdio -serial vc \\\n        -netdev user,id=net -device e1000e,addr=2.0,netdev=net \\\n        -device intel-hda,addr=1b.0 -device hda-duplex -device pcie-pci-bridge\n\nInside the VM, make sure that `jailhouse-*.bin`, generated by the build process,\nare available for firmware loading (typically /lib/firmware), see above for\ninstallation steps.\n\nThe Jailhouse QEMU cell config will block use of the serial port by the guest\nOS, so make sure that the guest kernel command line does NOT have its console\nset to log to the serial port (ie remove any 'console=ttyS0' arguments from the\ngrub config). Reboot the guest and load jailhouse.ko. Then enable Jailhouse\nlike this:\n\n    jailhouse enable /path/to/qemu-x86.cell\n\nNext you can create a cell with a demonstration application as follows:\n\n    jailhouse cell create /path/to/apic-demo.cell\n    jailhouse cell load apic-demo /path/to/apic-demo.bin\n    jailhouse cell start apic-demo\n\napic-demo.bin is left by the built process in the inmates/demos/x86 directory.\nThis application will program the APIC timer interrupt to fire at 10 Hz,\nmeasuring the jitter against the PM timer and displaying the result on the\nconsole. Given that this demonstration runs in a virtual machine, obviously\nno decent latencies should be expected.\n\nAfter creation, cells are addressed via the command line tool by providing\ntheir names or their runtime-assigned IDs. You can obtain information about\nactive cells this way:\n\n    jailhouse cell list\n\nCell destruction is performed by specifying the configuration file of the\ndesired cell. This command will destroy the apic-demo:\n\n    jailhouse cell destroy apic-demo\n\nNote that the first destruction or shutdown request on the apic-demo cell will\nfail. The reason is that this cell contains logic to demonstrate an ordered\nshutdown as well as the ability of a cell to reject shutdown requests.\n\nThe apic-demo cell has another special property for demonstration purposes: As\nlong as it is running, no cell reconfigurations can be performed - the\napic-demo locks the hypervisor in this regard. In order to destroy another cell\nor create an additional one, shut down the apic-demo first.\n\n    jailhouse cell shutdown apic-demo  # call again if error is returned\n\nTo demonstrate the execution of a second, non-Linux cell, issue the following\ncommands:\n\n    jailhouse cell create /path/to/pci-demo.cell\n    jailhouse cell load pci-demo /path/to/pci-demo.bin \\\n        -s \"con-base=0x2f8\" -a 0x1000\n    jailhouse cell start pci-demo\n\nThe pci-demo will use the second serial port provided by QEMU. You will find\nits output in a virtual console of the QEMU window. The purpose of this demo is\nto show basic PCI device configuration and MSI handling.\n\nWhile cell configurations are locked, it is still possible, though, to reload\nthe content of existing cell (provided they accept their shutdown first). To\nreload and restart the tiny-demo, issue the following commands:\n\n    jailhouse cell start apic-demo\n    jailhouse cell load pci-demo /path/to/pci-demo.bin \\\n        -s \"con-base=0x2f8\" -a 0x1000\n    jailhouse cell start pci-demo\n\nFinally, Jailhouse is can be stopped completely again:\n\n    jailhouse disable  # call again on error due to running apic-demo\n\nAll non-Linux cells running at that point will be destroyed, and resources\nwill be returned to Linux.\n\n\nARM64 Demonstration in QEMU\n---------------------------\n\nSimilarly like x86, Jailhouse can be tried out in a completely emulated ARM64\n(aarch64) environment under QEMU. QEMU version 3.0 or later is required.\n\nStart the QEMU machine like this:\n\n    qemu-system-aarch64 -cpu cortex-a57 -smp 16 -m 1G \\\n        -machine virt,gic-version=3,virtualization=on,its=off -nographic \\\n        -netdev user,id=net -device virtio-net-device,netdev=net \\\n        -drive file=LinuxInstallation.img,format=raw|qcow2|...,id=disk,if=none \\\n        -device virtio-blk-device,drive=disk \\\n        -kernel /path/to/kernel-image -append \"root=/dev/vda1 mem=768M\"\n\nJailhouse can be started after loading its kernel module. Run:\n\n    jailhouse enable /path/to/qemu-arm64.cell\n\nThe corresponding test to apic-demo on x86 is the gic-demo:\n\n    jailhouse cell create /path/to/qemu-arm64-inmate-demo.cell\n    jailhouse cell load inmate-demo /path/to/gic-demo.bin\n    jailhouse cell start inmate-demo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiemens%2Fjailhouse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiemens%2Fjailhouse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiemens%2Fjailhouse/lists"}