This page explains what you’ll need to run Celadon in a virtual machine.
Depending on your applications, you can run CiV using Intel® GVT-g technology, or allowing for GPU passthrough to a single Android guest VM through Intel® GVT-d technology, or VirtIO GPU, or pure software rendering.
A Intel NUC with 5th Generation or newer Intel Core Processors.
Ubuntu 20.04 (Focal Fossa) preinstalled which runs Linux* kernel version 5.0.0 or above.
Intel Graphics Virtualization Technology covers three distinct flavors of graphics virtualization approaches. Among these approaches, Intel GVT-d is based on Intel® VT-d technology, it also includes additional graphics related configuration options when compared to standard NIC pass-through devices. Intel® GVT-d allows direct assignment of an entire GPU’s capacity to a single user, passing the native driver capabilities through the hypervisor without limitations.
Refer to this article for introduction on Intel Graphics Virtualization Technology.
Set up QEMU and Intel GVT technology
The host device that launches the virtual machine requires Ubuntu 20.04.
To simpify the preparation works, a helper script
The script re-builds the
OVMF.fd firmware and QEMU emulator
from source depending on the target graphics virtualization technology,
and installs the required software on the installed Ubuntu system for running
Celadon in a VM with QEMU.
$ mkdir -p ~/civ && cd ~/civ $ tar zxvf caas-releasefiles-<$buildvariant>.tar.gz $ chmod +x scripts/setup_host.sh
Launch the script with no argument to set up the environment for running CiV using Intel GVT technology:
$ sudo -E ./scripts/setup_host.sh
During the installation, you will be prompted by some questions to confirm the
changes to the packages, it’s safe to respond
y to all of them.
Use Celadon kernel
The Linux kernel is extremely important on every Android devices, Google
recommends using AOSP common kernels on Android devices to include
features and implementations required by Android.
In addition to the AOSP common kernel, Celadon also integrates several
to take advantages of high performance new Intel processors,
so it’s strongly recommended to run the Celadon kernel as the host OS,
especially running CiV on NUC10i7FNK or NUC10i7FNH Intel NUC devices.
To that end, a
build.sh is designed to facilitate
the building and deploying of Celadon kerenl on a Ubuntu host.
Refer to the README for detailed instructions.
Refer to the Build Celadon in VM image section in the Getting Started Guide and
caas as the lunch target to build the CiV images. The
following CiV image types are generated at the end of the build:
Skip this section if you plan to boot the device directly with the GPT disk image
Follow the instructions below to create and set up CiV partitions on a qcow2 formatted virtual disk.
Run the helper script
$ cd ~/civ $ sudo ./scripts/start_flash_usb.sh caas-flashfiles-eng.<user>.zip
By running the
start_flash_usb.shscript, a QEMU window will be popped up, it will drop to the built-in UEFI Shell and start flashing the partitions to the virtual disk image.
The QEMU window will be closed automatically once flash complete. Now we get the CiV virtual disk
android.qcow2under the current directory.
A script start_civ.sh is developed to facilitate the CiV images booting process. It supports various options:
start_civ.sh [-h] [-m] [-c] [-g] [-d] [-f] [-v] [-s] [-p] [-b] [-e] [--passthrough-pci-usb] [--passthrough-pci-audio] [--passthrough-pci-eth] [--passthrough-wifi] [--thermal-mediation] [--battery-mediation] [--guest-pm-control] [--guest-time-keep]
||show this help message.|
||specify guest memory size, eg. “-m 4G”. Default is 2G if this is not specified.|
||specify guest cpu number, eg. “-c 4”. Default is 1 if this is not specified.|
specify guest graphics mode, current support VirtIO | GVT-g | GVT-d | QXL.
VirtIO GPU, eg. “-g VirtIO”
QXL VGA, eg. “-g QXL”
GVT-g, eg. “-g GVT-g,uuid=4ec1ff92-81d7-11e9-aed4-5bf6a9a2bb0a”, if uuid is not specified, a hardcoded uuid will be used
GVT-d: romfile is supported for GVT-d, eg. “-g GVT-d,romfile=/path/to/romfile”, romfile is optional.
The default value is VirtIO if this parameter is not specified.
||specify guest virtual disk image, eg. “-d /path/to/android.img”. Default is “$PWD/android.qcow2” if this is not specified.|
||specify guest firmware image, eg. “-d /path/to/ovmf.fd”. Default is “$PWD/OVMF.fd” if this is not specified.|
||specify guest vsock cid, eg. “-v 4”. Default is 3.|
||specify guest share folder path, eg. “-s /path/to/share/with/guest”.|
||specify host forward ports, current support adb/fastboot, eg. “-p adb=6666,fastboot=7777”. Default is adb=5555,fastboot=5554|
||specify host block device as guest virtual device, eg.” -b /dev/mmcblk0 “|
||specify extra qemu cmd, eg. “-e “-full-screen -monitor stdio”“|
||passthrough USB PCI bus to guest.|
||passthrough Audio PCI bus to guest.|
||passthrough Ethernet PCI bus to guest.|
||passthrough WiFi PCI bus to guest.|
||enable thermal mediation.|
||enable battery mediation.|
||allow guest control host PM.|
||reflect guest time setting on Host OS.|
Intel GVT option
Enter the following commands to run the script start_civ.sh with root permissions to facilitate the booting of CiV images with QEMU.
$ cd ~/civ # The following command runs CiV using Intel GVT-g $ sudo -E ./scripts/start_civ.sh -g GVT-g
# The following command runs CiV using Intel GVT-d, and passes # all the attached USB devices such as keyboard, mouse to the VM. $ sudo -E ./scripts/start_civ.sh -g GVT-d --passthrough-pci-usb
USB PCI controller pass-through option
You can pass-through not only the GPU but also the USB host controller (xHCI) to the Android VM, in order to attach all the connected USB devices (e.g. camera, USB thumb drive) to the VM. By passing --passthrough-pci-usb argument to the start_civ.sh script, all the USB devices connected to the platform get automatically enumerated inside the Android VM:
# The following command pass-through the xHCI to the VM $ sudo -E ./scripts/start_civ.sh --passthrough-pci-usb
All the USB devices, including keyboard and mouse, will be disconnected from the host OS and get attached to the Android VM.
An alternative methodology is to passthrough only selected USB devices to the Android VM by modifying the start_civ.sh script. For example, to pass-through the USB SD card reader in the following list, whose vendorID and productID are 14cd and 125c respectively:
$ lsusb Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 001 Device 003: ID 8087:0a2b Intel Corp. Bus 001 Device 005: ID 093a:2510 Pixart Imaging, Inc. Optical Mouse Bus 001 Device 004: ID 1c4f:0002 SiGma Micro Keyboard TRACER Gamma Ivory Bus 001 Device 008: ID 14cd:125c Super Top SD card reader
Execute start_civ.sh script as below, to enumerate the device in the Android VM:
sudo -E ./scripts/start_civ.sh -e "-device usb-host,vendroidid=0x14cd,productid=0x125c"
Launching with SD card
In case your hardware platform supports SD cards through the SDHCI controller, you can enable SDHCI mediation by adding -b <sdcard block device> option argument while invoking the start_civ.sh script if the SD card is present in the slot.
With the following command, the SD card interface will be mediated to the Android guest OS, and Android will mount the SD card on boot. The external SD card mount is validated with sdcardfs file system and the mount point is available in the standard UI interfaces like file explorer, storage settings etc.
$ sudo -E ./scripts/start_civ.sh -b /dev/mmcblk0p1
- This option should be given only if SD card is present in the slot.
- Do not specify --passthrough-pci-usb argument together with the SD card options, or the SD card won’t be operational.
Audio pass-through option
The audio controller can be passd through to the guest by adding --passthrough-pci-audio argument while invoking the start_civ.sh script, the host then has no control over it.
$ sudo -E ./scripts/start_civ.sh --passthrough-pci-audio
With the above setup, PCI controllers, which are part of the same IOMMU group as the audio controller, will also be pass-through to the guest. For example, if the Ethernet controller and the audio controller are in the same IOMMU group, the Ethernet controller will be moved to the guest. Thus if you are connecting to the host via Ethernet, the network accesses to the host will be drop. Since the Android guest has accesses to the Ethernet controller, you can connect to it using the command:
$ adb connect <guest-ip-addr>:5555