Jailhouse¶

Both the AM6254 and the AM62P54 processors include a hypervisor.

TI has ported the hypervisor control to support using the Seimen's jailhouse controller, which provides the ability to isolate the Cortex A53 cores and run independent software images on them. TI documents how to build jailhouse images on their processor SDK manuals in The Processor SDK Users Guide.

Critical Link has adapted the examples provided by TI to run on the 2 GB versions of the MitySOM-AM62x and the MitySOM-AM62P processors, and also on the 8 GB MitySOM-AM62P module. The inmate console port was changed from UART1 to UART2 as the MitySOM-AM62x Development Kit allocates all of the UART1 pins to alternate functions. The UART2 pins that are mapped to the expansion header may be used to monitor the console output of the examples.

Running the examples¶

Pre-compiled SD card images with support for jailhouse for the MitySOM-AM62x and MitySOM-AM62Px DevKits are included in the Repositories_and_Pre-built_Images page.

Linux Inmate¶

The linux inmate allocates 3 CPUs for the inmate cell along with 512 MB of memory. The following commands will start the inmate slave. The inmate console can be monitored by attaching a UART device (in our case, a USB to 3.3V adapter).

root@mitysom-am62px:~# modprobe jailhouse
root@mitysom-am62px:~# cd /usr/share/jailhouse
root@mitysom-am62px:/usr/share/jailhouse# ./linux-demo.sh

The examples include a shared memory ethernet driver that allows ethernet communications between the host and the inmates. This is demonstrated with the following commands on the host.

root@mitysom-am62px:/usr/share/jailhouse# ifconfig enp0s1 192.168.0.2
root@mitysom-am62px:/usr/share/jailhouse# ping 192.168.0.3

There are also example that will exercise a shared memory transfer with interrupt notifiers.

root@mitysom-am62px:/usr/share/jailhouse# ivshmem-demo

The inmate cell can be shutdown and destroy with the following commands:

root@mitysom-am62px:/usr/share/jailhouse# jailhouse cell shutdown 1
root@mitysom-am62px:/usr/share/jailhouse# jailhouse cell destroy 1

Bare metal UART example¶

root@mitysom-am62px:/usr/share/jailhouse# cd cells
root@mitysom-am62px:/usr/share/jailhouse/cells# jailhouse cell create k3-mitysom-am62p-devkit-8GB-inmate-demo.cell
root@mitysom-am62px:/usr/share/jailhouse/cells# cd ../inmates
root@mitysom-am62px:/usr/share/jailhouse/inmates# jailhouse cell load 1 uart-demo.bin
root@mitysom-am62px:/usr/share/jailhouse/inmates# jailhouse cell start 1

Building the inmate filesystem / image (via yocto)¶

If you are new to Linux, building and understanding Yocto can be difficult. We recommend starting with our provided setup so you can confirm your build environment is working before you make your customizations. You may contact Critical Link for help with your Yocto build or if you want us to customize it for you.

We recommend using a Linux-based host PC for your Yocto build. The exact version you use (Ubuntu, Fedora, etc.) is not critical as long as it supports Docker. At Critical Link, we typically recommend using an Ubuntu LTS release for your host PC.

Please use our forums if you have questions about installing Docker.

Alternate operating systems like MS Windows or Mac OSX also support Docker, so they could be tried in dire situations.

A Yocto build will heavily stress your build PC. You will likely need 500+GB of storage. 2GB of free RAM per cpu core is recommended by Yocto, if you have less you should reduce the PARALLEL_MAKE and/or BB_NUMBER_THREADS jobs. Depending on the speed of your machine, a build could require 4-5 hours of build time, depending on the options you select. Storage and Memory speed will have a significant impact on build time. The Yocto build environment will cache many build results so subsequent builds with minor changes will not require as much time.

Download the Critical Links oe-layersetup and meta-layers¶

A Yocto build uses build instructions, called recipes, to generate a filesytem. Various recipes are collected into meta-layers that provide related recipes for a specific purpose. For instance, meta-ti contains recipes that support various TI hardware. Critical Link also has its own meta-layer, meta-mitysom, that contains Yocto modifications for our various product lines (including the MitySOM-AM62).

Standard yocto builds require downloading a list of meta-layers from different git repos. TI has created a tool (oe-layersetup) that captures this setup into a script and some config files. We've expanded on this tool to add the customizations needed to run our module.

Note: These instructions use a special docker image that has been designed to contain everything needed for a Yocto build, crops/poky:ubuntu-18.04. The crops project has multiple docker images that support various Yocto releases. While you can roll your own docker image or even run the build directly on a Linux install, we have found that using a stable docker image keeps builds consistent over a long period of time.

The docker-poky.sh script automates launching the docker and executing the following command inside the docker. If no argument is provided, it will start an interactive shell. It mounts your current working directory as /work inside the docker and changes to the /work directory before running the command so it appears seemless.

Note: If you run the setup or build commands using the docker and then forget the docker commands the next time, you will get a lot of errors since the path to the meta layers will have changed. If you get stuck, you may need to delete the build directory and start again, though usually retrying with the docker command again is sufficient.

• Download the oe-layersetup repo
  

  git clone https://support.criticallink.com/git/oe-layersetup.git
  cd oe-layersetup
  

• Edit the jailhouse configuration for your SOM. Use a text editor and edit the configs/processor-sdk/processor-sdk-scarthgap-jailhouse-10.00.07.04-cl-config.txt file. You need to uncomment the appropriate lines at the bottom of the file based on the MitySOM configuration (AM62P vs. AM62x and memory size) you are targeting.
• Start a docker interactive shell. This may take some time if you have not downloaded the docker image already (it will need to fetch the image).
  

  ./docker-poky.sh
  

• Fetch / setup the configuration. In the docker shell, run:
  

  ./oe-layertool-setup.sh -f configs/processor-sdk/processor-sdk-scarthgap-jailhouse-10.00.07.04-cl-config.txt
  

Building the Filesystem Images¶

Within the docker shell, build the jailhouse SDK image with the following commands.

cd build
. ./conf/setenv
MACHINE=mitysom-am62x bitbake -k tisdk-jailhouse-image

Note, if you are building for the AM62P, then set the MACHINE argument to mitysom-am62px.

This build will take a fair amount of time. When it completes, there should be a wic image in the deploy-ti/images/mitysom-am62x subfolder.