Jailhouse Guide

Jailhouse

Jailhouse Introduction

Jailhouse is a partitioning Hypervisor based on Linux. It is able to run bare-metal applications or (adapted) operating systems besides Linux. 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
imx8mn-var-som	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 imx8mn-var-som:

1. Creating Linux device tree files: imx8mn-var-som: Add jailhouse device tree files
2. Adding Linux device tree files to image: imx8mn-var-som: Add jailhouse device tree files to image
3. 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 steps 1-3 of the Yocto Build Release page.
• Setup build environment

$ cd ~/var-fslc-yocto
$ MACHINE=imx8mn-var-som DISTRO=fslc-xwayland . setup-environment build_xwayland

• Add the following line to local.conf

DISTRO_FEATURES_append = " jailhouse"

Build a recovery SD card with Jailhouse Support

$ bitbake fsl-image-gui

• Create the "SWUpdate recovery SD card"

$ sudo MACHINE=imx8mn-var-som ../sources/meta-variscite-fslc/scripts/var_mk_yocto_sdcard/var-create-yocto-sdcard.sh /dev/sdX
(Replace /dev/sdX with your actual device)

• Boot the board using the created SD card. See more info here.
• Install the Jailhouse image to the eMMC using the install_yocto.sh.

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: