This page explains what you’ll need to run Celadon in a virtual machine.
Running Celadon in VMs requires Intel Graphics Virtualization Technology (GVT) to deliver excellent virtual GPU performance in VMs. Depending on your applications, you can run CiV using Intel® GVT-g technology (default), or allowing for GPU passthrough to a single Android guest VM through Intel® GVT-d technology.
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-g technology:
$ sudo -E ./scripts/setup_host.sh
Or, pass --gvtd argument to the script for setting up an Intel GVT-d environment:
$ sudo -E ./scripts/setup_host.sh --gvtd
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.
After setting up the Intel GVT-d environment, your Ubuntu host is configured to disable GUI desktop on next boot. It’s required to run the host OS in text mode, so that the GPU can be pass-through to the Android VM. To start GUI destkop temporary, run the following command:
$ sudo systemctl start gdm3
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.
start_android_qcow2.sh is developed to facilitate the CiV images
booting process. However, before launching the script to boot to the Android UI,
you may need to edit the CiV image filename in the script, as the default image
android.qcow2 is hard-coded in the script:
#!/bin/bash work_dir=$PWD caas_image=$work_dir/android.qcow2 ...
Intel GVT option
Enter the following commands to run the script
root permissions to facilitate the booting of CiV images with QEMU.
The script utilizes Intel GVT-g for graphics virtualization by default,
you can pass --gvtd argument to the script to run the CiV images
using Intel GVT-d technology.
$ cd ~/civ # The following command runs CiV using Intel GVT-g $ sudo -E ./scripts/start_android_qcow2.sh
# 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_android_qcow2.sh --gvtd --usb-host-passthrough
xHCI 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 --usb-host-passthrough argument to the
start_android_qcow2.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_android_qcow2.sh --usb-host-passthrough
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
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
Add a new setting to the “common_usb_device_passthrough” list in the
start_android_qcow2.sh script as below, to enumerate the device
in the Android VM:
... common_usb_device_passthrough="\ -device qemu-xhci,id=xhci,addr=0x8 \ `/bin/bash $usb_switch` \ -device usb-host,vendorid=0x03eb,productid=0x8a6e \ -device usb-host,vendorid=0x0eef,productid=0x7200 \ -device usb-host,vendorid=0x222a,productid=0x0141 \ -device usb-host,vendorid=0x222a,productid=0x0088 \ # Pass-through specific USB device as below \ -device usb-host,vendorid=0x14cd,productid=0x125c \ $bt_passthrough \ ...
Launching with SD card
In case your hardware platform supports SD cards through the SDHCI controller, you can enable
SDHCI mediation by adding --sdonly or --sdemmc-coexist
argument while invoking the
start_android_qcow2.sh script if the
SD card is present in the slot. The argument --sdemmc-coexist
is used if the SDHCI controller supports both SD and eMMC cards, and
the SD card partiton is present on the
or --sdonly should be used, and the SD card is present on the
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_android_qcow2.sh --sdonly
- This option should be given only if SD card is present in the slot.
- Do not specify --usb-host-passthrough argument together with the SD card options, or the SD card won’t be operational.
Audio pass-through option
In Intel GVT-d setup, the audio controller can be passd through to the guest
by adding --audio-passthrough argument while invoking the
start_android_qcow2.sh script, the host then has no control over it.
$ sudo -E ./scripts/start_android_qcow2.sh --gvtd --usb-host-passthrough --audio-passthrough
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