Launching an Android guest

Updated: March 11, 2025

This chapter covers how to create and launch an Android guest on the QNX Hypervisor AMI. It contains the following topics:

Meeting the hardware requirements

Your host should meet or exceed the following hardware requirements:
  • A 64-bit x86 system
  • At least 400GB of disk space
  • A minimum 64GB of RAM
For details on hardware requirements, go to the Android OS Documentation at https://source.android.com/docs/setup/start/requirements#hardware-requirements.

Installing the required software

Your host must use Ubuntu 18.04 or later. To install the required packages, run the following command:
sudo apt-get install git-core gnupg flex bison build-essential zip curl
                      zlib1g-dev libc6-dev-i386 x11proto-core-dev
                      libx11-dev lib32z1-dev libgl1-mesa-dev libxml2-utils
                      xsltproc unzip fontconfig libncurses5
Then install Repo by following Google's instructions: https://source.android.com/docs/setup/start/requirements#install-software
Note: These steps were tested on Ubuntu 22.04. Other versions may have additional dependencies.

Downloading the Android components

You can make your host workspace and download the Android components into it with the following steps:
  1. Make the workplace directory for your Android project:
    mkdir a14_r2 && cd a14_r2
    export WORKSPACE=$PWD
  2. Make the Android kernel directory $WORKSPACE/android-kernel, change into it, and then download the Android kernel:
    mkdir $WORKSPACE/android-kernel && cd $WORKSPACE/android-kernel
    repo init -u https://android.googlesource.com/kernel/manifest -b trout-android12-5.10
    repo sync -c -j8
  3. Change the directory to common and checkout android12-5.10-2023-03 from Git:
    cd common
    git fetch aosp
    git checkout deprecated/android12-5.10-2023-03
    cd ..
  4. Make the Android Open-Source Project (AOSP) directory $WORKSPACE/aosp, change into it, and then download the Android branch:
    mkdir $WORKSPACE/aosp && cd $WORKSPACE/aosp
    repo init -u https://android.googlesource.com/platform/manifest -b android-14.0.0_r2
    repo sync -c -j8
    Note: The kernel android-14.0.0_r2 has no changes from its branch trout-android12-5.10.

Applying QNX Git patches

You must apply the QNX Git patches to the following Android directories in $WORKSPACE:
  • android-kernel/common
  • android-kernel/common-modules/virtual-device
  • aosp/device/google/cuttlefish
  • aosp/external/v4l2_codec2
  • aosp/frameworks/av
  • aosp/system/sepolicy
  • aosp/system/sepolicy
You can use the following commands to apply the QNX Git patches:
cd $WORKSPACE/android-kernel/common
curl https://gitlab.com/qnx/hypervisor/aosp/kernel_common/-/raw/android12-5.10-
2023-03-qnx/common_changes_d0782c9411db46ff9fc9120ff5fc5e173088bcd2.diff | git 
apply

cd $WORKSPACE/android-kernel/common-modules/virtual-device
curl https://gitlab.com/qnx/hypervisor/aosp/kernel_common-modules_virtual-devic
e/-/raw/trout-android12-5.10-qnx/virtual-device_changes.diff | git apply

cd $WORKSPACE/aosp/device/google/cuttlefish
curl https://gitlab.com/qnx/hypervisor/aosp/device_google_cuttlefish/-/raw/andr
oid-14.0.0_r2-qnx/device_google_cuttlefish.diff | git apply

cd $WORKSPACE/aosp/external/v4l2_codec2
curl https://gitlab.com/qnx/hypervisor/aosp/platform_external_v4l2_codec2/-/raw
/android-14.0.0_r2-qnx/v4l2_codec2_changes.diff | git apply

cd $WORKSPACE/aosp/frameworks/av
curl https://gitlab.com/qnx/hypervisor/aosp/platform_frameworks_av/-/raw/androi
d-14.0.0_r2-qnx/platform_frameworks_av.diff | git apply

cd $WORKSPACE/aosp/packages/services/Car
curl https://gitlab.com/qnx/hypervisor/aosp/platform_packages_services_car/-/ra
w/android-14.0.0_r2-qnx/packages_services_Car.diff | git apply

cd $WORKSPACE/aosp/system/sepolicy
curl https://gitlab.com/qnx/hypervisor/aosp/platform_system_sepolicy/-/raw/andr
oid-14.0.0_r2-qnx/platform_system_sepolicy.diff | git apply

Cloning and building the Android guest

After setting up your host workplace with the Android components, you need to clone the Android guest repository to your host and then build the guest.

To assemble the Android guest:
  1. Make the directory $WORKSPACE/aosp/device/qnx, change into it, and clone the Android guest repository:
    mkdir -p $WORKSPACE/aosp/device/qnx && cd $WORKSPACE/aosp/device/qnx
    git clone https://gitlab.com/qnx/hypervisor/aosp/device_qnx_warbler.git warbler
  2. Change the directory to $WORKSPACE, export the Android guest, and then build the guest:
    cd $WORKSPACE
    export ANDROID_SOURCE=aosp
    export ANDROID_KERNEL_SOURCE=android-kernel
    export ANDROID_VARIANT=aosp_warbler_arm64-userdebug
    export ANDROID_DEVICE=warbler_arm64
    . ./aosp/device/qnx/warbler/tools/a14_disk_image_build.sh
Rebuilding tips after building the Android guest

After building the Android guest for the first time, you may want to configure it. Every time you configure the Android guest files, you'll need to rebuild the Android guest to apply the changes. If you're rebuilding the guest frequently, you can skip the rebuild step.

You can skip clearing and rebuilding AOSP by setting ANDROID_CLOBBER to false:
export ANDROID_CLOBBER=false
If you're not making kernel changes, you can skip rebuilding the kernel by setting BUILD_KERNEL_LOCALLY to false (but remember to re-enable it if you make kernel changes):
export BUILD_KERNEL_LOCALLY=false

Installing and running the Android guest

After building your Android guest, you install the built guest to your cloud target and run it.

To install the Android guest:
  1. Copy the following Android guest files from the host out/target/product/warbler_arm64/out_for_qvm/ to the cloud target /guests/android/Android14-auto/:
    • sa8155-vm.dtb. After copying the file, rename it to graviton2-vm.dtb.
    • kernel-5.10.generic. After copying the file, rename it to kernel-5.10.
    • android14-disk.img
    • vendor_ramdisk
  2. Run the Android guest on the cloud target:
    qvm @/guests/android/Android14-auto/a14-aarch64-auto.conf

Connecting to the Android guest

You can connect to the guest target using the IP of the QNX host:
adb connect 10.0.0.123

Stopping the Android QVM process after running the Android guest

If you configured the Android guest files and rebuilt the guest, then you must slay the QVM process of the previous Android guest on the target before copying your rebuilt Android guest files to the target.
CAUTION:
If you copy files to the target before slaying the QVM process, then you can corrupt the target filesystem.
Slay the Android QVM process by running slay qvm to ensure that it stops using the target filesystem.