Jailhouse Guide
Jailhouse Introduction
Jailhouse is a partitioning Hypervisor based on Linux. It is able to run bare-metal applications or (adapted) operating systems in addition to a standard Linux kernel on one multicore hardware platform. For this purpose, it configures CPU and device virtualization features of the hardware platform in a way that none of these domains, called "cells" here, can interfere with each other in an unacceptable way.
Jailhouse is optimized for simplicity rather than feature richness. Unlike full-featured Linux-based hypervisors like KVM or Xen, Jailhouse does not support overcommitment of resources like CPUs, RAM or devices. It performs no scheduling and only virtualizes those resources in software, that are essential for a platform and cannot be partitioned in hardware.
Once Jailhouse is activated, it runs bare-metal, i.e. it takes full control over the hardware and needs no external support. However, in contrast to other bare-metal hypervisors, it is loaded and configured by a normal Linux system. Its management interface is based on Linux infrastructure. So you boot Linux first, then you enable Jailhouse and finally you split off parts of the system's resources and assign them to additional cells.
Variscite Jailhouse Supported Modules
NXP provides several Jailhouse examples. Please refer to https://www.nxp.com/docs/en/user-guide/IMX_LINUX_USERS_GUIDE.pdf for documentation from NXP.
Some examples have been ported to the following Variscite SOMs:
| Variscite SOM | Kernel version |
|---|---|
| VAR-SOM-MX8M-NANO | 5.4-2.1.x-imx_var01 or newer |
The examples from NXP are configured for NXP EVKs and require minor changes to run on Variscite modules. In particular:
- Jailhouse root and inmate shared memory allocation must be moved from the end of 2 GiB to the end of 1 GiB.
- Jailhouse devices such as MMC, UARTS, etc. must be changed to match Variscite Hardware.
The patches below demonstrate porting Jailhouse for the VAR-SOM-MX8M-NANO:
- Creating Linux device tree files: imx8mn-var-som: Add jailhouse device tree files
- Adding Linux device tree files to image: imx8mn-var-som: Add jailhouse device tree files to image
- Aligning imx-jailhouse cells to match Linux device tree files: 0001-imx8mn-var-som-move-to-1-gib-domain.patch
Build Yocto Image with Jailhouse Support
- Follow the Build Yocto from source code page, but before running the bitbake command in the "Setup and build Yocto" section, append the following line to the conf/local.conf file under your Yocto build directory:
DISTRO_FEATURES_append = " jailhouse" IMAGE_INSTALL_append = " jailhouse"
- Install the image to the eMMC (e.g. by following the "Create an extended SD card" section in the same page linked above, then booting from the extended SD card and running install_yocto.sh on the board).
Running Jailhouse Examples
Note: Make sure you are booting from eMMC as described above. The Jailhouse root device tree file allocates the SD card to the Jailhouse inmate.
Configure U-Boot to load the Jailhouse root device tree:
# fw_setenv fdt_file imx8mn-var-som-symphony-root.dtb
Optionally increase kernel log level:
# echo "sysctl kernel.printk=7" >> ~/.profile
Finally, reboot for changes to take effect
# reboot
ivshmem Example
- Load drivers and run ivshmem-demo cell:
# export PATH=$PATH:/usr/share/jailhouse/tools # modprobe jailhouse # modprobe uio_ivshmem # jailhouse enable /usr/share/jailhouse/cells/imx8mn.cell # jailhouse cell create /usr/share/jailhouse/cells/imx8mn-ivshmem-demo.cell # jailhouse cell load 1 /usr/share/jailhouse/inmates/ivshmem-demo.bin # jailhouse cell start 1
- Run the ivshmem-demo (it is best to run this from another shell via SSH)
# ivshmem-demo /dev/uio0 1
Dual Linux OS Example
- Insert the Recovery SD card. This will be used as the rootfs for the second Linux OS (/dev/mmcblk1p1)
- Connect your host PC using a USB to TTL adapter to J18-3 and J18-5 (UART3, /dev/ttymxc2)
- Load drivers and run second Linux OS:
# export PATH=$PATH:/usr/share/jailhouse/tools # modprobe jailhouse # modprobe uio_ivshmem # jailhouse enable /usr/share/jailhouse/cells/imx8mn.cell # jailhouse cell linux /usr/share/jailhouse/cells/imx8mn-linux-demo.cell /boot/Image.gz \ -d /boot/imx8mn-var-som-inmate.dtb \ -c "clk_ignore_unused console=ttymxc2,115200 \ earlycon=ec_imx6q,0x30a60000,115200 root=/dev/mmcblk1p1 rootwait rw"
The second Linux OS will boot with it's console on J18-3 and J18-5
Please see this YouTube video for a full demonstration: