DornerWorks

VM Composer User Guide

VM Composer User Guide

Table of contents

VM Composer Description

VM Composer is a suite of tools that generates configurations of the camkes-vm based on user input and configuration. It is made up of two tools, a front-end GUI, referred to as VM Composer, and a back-end tool that performs utility
functions, such as code generation and building the source into a loadable image.

All of the tools use a JSON file, which is specified by VM Composer, to understand the project configuration. This acts as the project file and can be loaded in and updated by the GUI. The GUI can automate usage of the back-end tool with the JSON file to allow for push-button generation of an image. Or the back-end tools can be called via command line for more advanced controls.

The tool provides a distribution of the camkes-vm and necessary code. A custom manifest can be specified so that users can use their own distribution, but some features might not work in that case. The tool also performs some configuration validation.

Installation

Installation was verified on Ubuntu 18.04.

  1. Copy the release tarball onto the system and unpack it.
$ cd
$ tar xf vm-composer-1.0.0.tar.gz
$ cd vm-composer-1.0.0
  1. Install dependencies
$ sudo apt install vim curl git python3.6 python3-pip docker.io repo
  1. Install seL4 docker following the install instructions.
  • Note: The docker socket’s permissions may need to be modified in order to
    launch the seL4 docker container.
$ sudo chmod 666 /var/run/docker.sock
  1. Install vmcomp.tar.gz.
$ pip3 install vmcomp.tar.gz
  • Note: If vmcomp is not found on the machine, its path may need to be added to $PATH in ~/.bashrc.
$ vim ~/.bashrc

Add export PATH="$HOME/.local/bin:$PATH".

$ source ~/.bashrc
  1. Install the bootgen docker container.
$ docker pull dornerworks/bootgen
$ docker image tag dornerworks/bootgen:latest bootgen:latest
  1. Install the application to a directory on your path to use the
    vm-composer tool from anywhere on the system.
$ sudo cp vm-composer.AppImage /usr/local/bin/

Notes on Current Release

Current supported platforms are Ultra96 and ZCU102. All devices except DMA, I2C and SPI have been fully tested.

The prebuilt files used when not supplying a VM’s kernel image or rootfs include drivers for many Ultra96 devices such as WIFI and USB.

Usage

  1. Start up the VM Composer GUI.
$ vm-composer.AppImage
  1. Create a New Project and choose a Project Name and Project Directory. Use the following settings.
Feature Set: All
Target Hardware: Ultra96
Scheduling Algorithm: Single-core Exclusive
  1. Existing projects can also be opened.
  2. Create a new VM by dragging a VM node from the toolbox to the editor.
    1. Click the Wrench and Screwdriver to edit the VM node.
    2. From here you can configure the VM.
      • VM Name
      • OS (Linux only currently tested OS)
      • CPU core (1 per VM)
      • RAM amount
      • RAM address (No overlap between VMs)
      • Custom Kernel Image (If no image is supplied a prebuilt default image will be used)
      • Custom Root Filesystem (If no rootfs is supplied a prebuilt default rootfs will be used)
    3. Physical I/O can be passed though to the VM.
    4. Virtual Channels can be passed though to the VM. This requires multiple VMs to be created.
    5. Virtual I/O can be passed to the VM. These require various VirtServers to be created.
  3. Create a new VirtServer by dragging a VirtServer node from the toolbox to the
    editor.

    1. Click the Wrench and Screwdriver to edit the VirtServer.
    2. From here you can configure the VirtServer.
      • VirtServer Name
      • Interface Type
        • virtio-serial
      • Passive or Bound to a CPU core
      • Bind Physical I/O device
      • Virtual I/O to VMs
  4. Save the Config using File -> Save.
  5. Build the seL4 image by clicking the Build it! button in the toolbox.
  6. Once complete, the seL4 image is found at
    sel4_hyp/build_<proj_name>/images/capdl-loader-image-arm-zynqmp
  7. The BOOT.bin is found at sel4_hyp/bootbin/BOOT.bin

Configuring a VM with Multiple Cores

  1. Start up the VM Composer GUI.
$ vm-composer.AppImage
  1. Create a New Project and choose a Project Name and Project Directory. Use the following settings.
Feature Set: All
Target Hardware: Ultra96
Scheduling Algorithm: Multi-core Exclusive
  1. Create a new VM by dragging a VM node from the toolbox to the editor.
    1. Click the Wrench and Screwdriver to edit the VM node.
    2. From here you can configure the VM.
      • VM Name
      • OS (Linux only currently tested OS)
      • CPU cores
      • RAM amount
      • RAM address (No overlap between VMs)
      • Custom Kernel Image (If no image is supplied a prebuilt default image will be used)
      • Custom Root Filesystem (If no rootfs is supplied a prebuilt default rootfs will be used)

Configuring a VM with the MCS Scheduler

  1. Start up the VM Composer GUI.
$ vm-composer.AppImage
  1. Create a New Project and choose a Project Name and Project Directory. Use the following settings.
Feature Set: All
Target Hardware: Ultra96
Scheduling Algorithm: Mixed Criticality Systems (MCS) scheduler
  1. Create a new VM by dragging a VM node from the toolbox to the editor.
    1. Click the Wrench and Screwdriver to edit the VM node.
    2. From here you can configure the VM.
      • VM Name
      • OS (Linux only currently tested OS)
      • CPU cores
      • RAM amount
      • RAM address (No overlap between VMs)
      • Custom Kernel Image (If no image is supplied a prebuilt default image will be used)
      • Custom Root Filesystem (If no rootfs is supplied a prebuilt default rootfs will be used)
  2. Select Configure Project in the upper left corner
    1. For each selected core, provide a Period and a Budget
      • Note that Period must be greater than the budget
      • It is up to the user to provide values that are compatible with the overall project

Providing Custom Boot Images

  1. Start up the VM Composer GUI and either create a new project, or open an existing project.
$ vm-composer.AppImage
  1. Select Configure Project in the upper left corner
  2. Open the "Advanced Options" menu
  3. Use the Browse menu to populate the Custom Boot Binary File Paths

Providing Custom seL4 Source

  1. Start up the VM Composer GUI and either create a new project, or open an existing project.
$ vm-composer.AppImage
  1. Select Configure Project in the upper left corner
  2. Open the "Advanced Options" menu
  3. Select the Custom manifest checkbox. Then populate the revealed text fields with manifest
    information

Headless seL4 Generation

This section is on using the backend vmcomp tool. This is only needed if the GUI tool has already generated a JSON config file and a build is needed to be
run from CLI.

  1. Initialize the seL4 repo with -p, point to seL4 app directory with
    --output, and supply the JSON file.
$ vmcomp config Project.json -p --output ./sel4_hyp/projects/vm-apps/apps/Arm
  1. Move into the sel4_hyp directory and build the project.
$ cd sel4_hyp
$ vmcomp build ../Project.json
  1. Once complete, the seL4 image is found at sel4_hyp/build_<proj_name>/images/capdl-loader-image-arm-zynqmp and the BOOT.bin is found at sel4_hyp/bootbin/BOOT.bin

SD Card Setup

Format an SD card using these instructions.

Copy in the bootloader generated by the vmcomp tool:

$ cp bootbin/BOOT.bin <sd_card_boot_partition>/

SD Boot seL4

Copy the seL4 image to the SD card.

$ cp sel4_hyp/build_<proj_name>/images/capdl-loader-image-arm-zynqmp <sd_card_boot_partition>/Image

Interrupt U-Boot’s auto boot and run the following command:

ZynqMP> fatload mmc 0 0x0 Image && bootelf 0x0

VM Usage

Log into the default VMs with user root password root.
Switch between VMs by typing @ followed by VM number. e.g. @1 to switch to VM2. Note sometimes Enter must be pressed before @.

To setup Wifi on the default VM images run the following commands.

  1. Modify ~/wifi/wpa_supplicant.conf with your network info.
  2. Run ~/wifi/teardown_wifi.sh.
  3. Run ~/wifi/wifi.sh.