docs/getting_started.md - platform/packages/modules/Virtualization - Git at Google


            
            # Getting started with Android Virtualization Framework


            ## Step 1: Prepare a device


            We support the following devices:


            * aosp\_panther (Pixel 7)

            
            * aosp\_cheetah (Pixel 7 Pro)

            
            * aosp\_oriole (Pixel 6)

            
            * aosp\_raven (Pixel 6 Pro)

            
            * aosp\_felix (Pixel Fold)

            
            * aosp\_tangorpro (Pixel Tablet)

            
            * aosp\_cf\_x86\_64\_phone (Cuttlefish a.k.a. Cloud Android). Follow [this

            
              instruction](https://source.android.com/docs/setup/create/cuttlefish-use) to

            
              use.


            ### Note on Pixel 6 and 6 Pro

            
            AVF is shipped in Pixel 6 and 6 Pro, but isn't enabled by default. To enable

            
            it, follow the instructions below:


            1. If the device is running Android 13 or earlier, upgrade to Android 14.


            1. Once upgraded to Android 14, execute the following command to enable pKVM.

            
               ```shell

            
               adb reboot bootloader

            
               fastboot flashing unlock

            
               fastboot oem pkvm enable

            
               fastboot reboot

            
               ```

            
            ### Note on Cuttlefish

            
            Cuttlefish does not support protected VMs. Only non-protected VMs are

            
            supported.


            ## Step 2: Build Android image


            This step is optional unless you want to build AVF by yourself or try the

            
            in-development version of AVF.


            AVF is implemented as an APEX named `com.android.virt`. However, in order for

            
            you to install it to your device (be it Pixel or Cuttlefish), you first need to

            
            re-build the entire Android from AOSP. This is because the official Android

            
            build you have in your device is release-key signed and therefore you can't

            
            install your custom-built AVF APEX to it - because it is test-key signed.


            ### Pixel


            1. [Download](https://source.android.com/docs/setup/download/downloading)

            
               source code from AOSP. Use the `main` branch.


            1. [Download](https://developers.google.com/android/blobs-preview) the preview

            
               vendor blob that matches your device.


            1. [Build](https://source.android.com/docs/setup/build/building) the `aosp_`

            
               variant of your device. For example, if your device is Pixel 7 (`panther`),

            
               build `aosp_panther`.


            1. [Flash](https://source.android.com/docs/setup/build/running) the built

            
               images to the device.


            ### Cuttlefish


            1. [Download](https://source.android.com/docs/setup/download/downloading)

            
               source code from AOSP. Use the `main` branch.


            1. Build Cuttlefish:

            
               ```shell

            
               source build/envsetup.sh

            
               lunch aosp_cf_x86_64_phone-trunk_staging-userdebug

            
               m

            
               ```


            1. Run Cuttlefish:

            
               ```shell

            
               cvd create

            
               ```


            ## Step 3: Build AVF


            Then you can repeat building and installing AVF to the device as follows:


            1. Build the AVF APEX.

            
               ```sh

            
               banchan com.android.virt aosp_arm64

            
               UNBUNDLED_BUILD_SDKS_FROM_SOURCE=true m apps_only dist

            
               ```

            
               Replace `aosp_arm64` with `aosp_x86_64` if you are building for Cuttlefish.


            1. Install the AVF APEX to the device.

            
               ```sh

            
               adb install out/dist/com.android.virt.apex

            
               adb reboot; adb wait-for-device

            
               ```


            Similarly, for a non-AOSP Pixel target:


            1. Build the AVF APEX for the non-AOSP Pixel target:

            
               ```sh

            
               lunch <target>

            
               m com.google.android.virt

            
               ```


            1. Install the APEX to the non-AOSP Pixel target:

            
               ```sh

            
               adb install ${ANDROID_PRODUCT_OUT}/system/apex/com.google.android.virt.apex

            
               adb reboot; adb wait-for-device

            
               ```


            ## Step 4: Run a Microdroid VM


            [Microdroid](../../build/microdroid/README.md) is a lightweight version of Android

            
            that is intended to run on pVM. You can run a Microdroid-based VM with an empty

            
            payload using the following command:


            ```shell

            
            packages/modules/Virtualization/android/vm/vm_shell.sh start-microdroid --auto-connect -- --protected

            
            ```


            You will see the log messages like the below.


            ```

            
            found path /apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk

            
            creating work dir /data/local/tmp/microdroid/7CI6QtktSluD3OZgv

            
            apk.idsig path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/apk.idsig

            
            instance.img path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/instance.img

            
            Created VM from "/apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk"!PayloadConfig(VirtualMachinePayloadConfig { payloadBinaryName: "MicrodroidEmptyPayloadJniLib.so" }) with CID 2052, state is STARTING.

            
            [2023-07-07T14:50:43.420766770+09:00 INFO  crosvm] crosvm started.

            
            [2023-07-07T14:50:43.422545090+09:00 INFO  crosvm] CLI arguments parsed.

            
            [2023-07-07T14:50:43.440984015+09:00 INFO  crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/49

            
            [2023-07-07T14:50:43.441730922+09:00 INFO  crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/54

            
            [2023-07-07T14:50:43.462055141+09:00 INFO  crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/63

            
            [WARN] Config entry DebugPolicy uses non-zero offset with zero size

            
            [WARN] Config entry DebugPolicy uses non-zero offset with zero size

            
            [INFO] pVM firmware

            
            avb_slot_verify.c:443: ERROR: initrd_normal: Hash of data does not match digest in descriptor.

            
            [INFO] device features: SEG_MAX | RO | BLK_SIZE | RING_EVENT_IDX | VERSION_1 | ACCESS_PLATFORM

            
            [INFO] config: 0x201a000

            
            [INFO] found a block device of size 50816KB

            
            [INFO] device features: SEG_MAX | BLK_SIZE | FLUSH | DISCARD | WRITE_ZEROES | RING_EVENT_IDX | VERSION_1 | ACCESS_PLATFORM

            
            [INFO] config: 0x2022000

            
            [INFO] found a block device of size 10304KB

            
            [INFO] No debug policy found.

            
            [INFO] Starting payload...

            
            <omitted>

            
            07-07 05:52:01.322    69    69 I vm_payload: vm_payload: Notified host payload ready successfully

            
            07-07 05:52:01.364    70    70 I adbd    : persist.adb.watchdog set to ''

            
            07-07 05:52:01.364    70    70 I adbd    : persist.sys.test_harness set to ''

            
            07-07 05:52:01.365    70    70 I adbd    : adb watchdog timeout set to 600 seconds

            
            07-07 05:52:01.366    70    70 I adbd    : Setup mdns on port= 5555

            
            07-07 05:52:01.366    70    70 I adbd    : adbd listening on vsock:5555

            
            07-07 05:52:01.366    70    70 I adbd    : adbd started

            
            #

            
            ```


            The `--auto-connect` option provides you an adb-shell connection to the VM. The

            
            shell promot (`#`) at the end of the log is for that.


            ## Step 5: Run tests


            There are various tests that spawn guest VMs and check different aspects of the

            
            architecture. They all can run via `atest`.


            ```shell

            
            atest MicrodroidHostTestCases

            
            atest MicrodroidTestApp

            
            ```


            If you run into problems, inspect the logs produced by `atest`. Their location

            
            is printed at the end. The `host_log_*.zip` file should contain the output of

            
            individual commands as well as VM logs.
	# Getting started with Android Virtualization Framework

	## Step 1: Prepare a device

	We support the following devices:

	* aosp\_panther (Pixel 7)
	* aosp\_cheetah (Pixel 7 Pro)
	* aosp\_oriole (Pixel 6)
	* aosp\_raven (Pixel 6 Pro)
	* aosp\_felix (Pixel Fold)
	* aosp\_tangorpro (Pixel Tablet)
	* aosp\_cf\_x86\_64\_phone (Cuttlefish a.k.a. Cloud Android). Follow [this
	instruction](https://source.android.com/docs/setup/create/cuttlefish-use) to
	use.

	### Note on Pixel 6 and 6 Pro
	AVF is shipped in Pixel 6 and 6 Pro, but isn't enabled by default. To enable
	it, follow the instructions below:

	1. If the device is running Android 13 or earlier, upgrade to Android 14.

	1. Once upgraded to Android 14, execute the following command to enable pKVM.
	```shell
	adb reboot bootloader
	fastboot flashing unlock
	fastboot oem pkvm enable
	fastboot reboot
	```
	### Note on Cuttlefish
	Cuttlefish does not support protected VMs. Only non-protected VMs are
	supported.

	## Step 2: Build Android image

	This step is optional unless you want to build AVF by yourself or try the
	in-development version of AVF.

	AVF is implemented as an APEX named `com.android.virt`. However, in order for
	you to install it to your device (be it Pixel or Cuttlefish), you first need to
	re-build the entire Android from AOSP. This is because the official Android
	build you have in your device is release-key signed and therefore you can't
	install your custom-built AVF APEX to it - because it is test-key signed.

	### Pixel

	1. [Download](https://source.android.com/docs/setup/download/downloading)
	source code from AOSP. Use the `main` branch.

	1. [Download](https://developers.google.com/android/blobs-preview) the preview
	vendor blob that matches your device.

	1. [Build](https://source.android.com/docs/setup/build/building) the `aosp_`
	variant of your device. For example, if your device is Pixel 7 (`panther`),
	build `aosp_panther`.

	1. [Flash](https://source.android.com/docs/setup/build/running) the built
	images to the device.


	### Cuttlefish

	1. [Download](https://source.android.com/docs/setup/download/downloading)
	source code from AOSP. Use the `main` branch.

	1. Build Cuttlefish:
	```shell
	source build/envsetup.sh
	lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
	m
	```

	1. Run Cuttlefish:
	```shell
	cvd create
	```

	## Step 3: Build AVF

	Then you can repeat building and installing AVF to the device as follows:

	1. Build the AVF APEX.
	```sh
	banchan com.android.virt aosp_arm64
	UNBUNDLED_BUILD_SDKS_FROM_SOURCE=true m apps_only dist
	```
	Replace `aosp_arm64` with `aosp_x86_64` if you are building for Cuttlefish.

	1. Install the AVF APEX to the device.
	```sh
	adb install out/dist/com.android.virt.apex
	adb reboot; adb wait-for-device
	```

	Similarly, for a non-AOSP Pixel target:

	1. Build the AVF APEX for the non-AOSP Pixel target:
	```sh
	lunch <target>
	m com.google.android.virt
	```

	1. Install the APEX to the non-AOSP Pixel target:
	```sh
	adb install ${ANDROID_PRODUCT_OUT}/system/apex/com.google.android.virt.apex
	adb reboot; adb wait-for-device
	```

	## Step 4: Run a Microdroid VM

	[Microdroid](../../build/microdroid/README.md) is a lightweight version of Android
	that is intended to run on pVM. You can run a Microdroid-based VM with an empty
	payload using the following command:

	```shell
	packages/modules/Virtualization/android/vm/vm_shell.sh start-microdroid --auto-connect -- --protected
	```

	You will see the log messages like the below.

	```
	found path /apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk
	creating work dir /data/local/tmp/microdroid/7CI6QtktSluD3OZgv
	apk.idsig path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/apk.idsig
	instance.img path: /data/local/tmp/microdroid/7CI6QtktSluD3OZgv/instance.img
	Created VM from "/apex/com.android.virt/app/EmptyPayloadAppGoogle@MASTER/EmptyPayloadAppGoogle.apk"!PayloadConfig(VirtualMachinePayloadConfig { payloadBinaryName: "MicrodroidEmptyPayloadJniLib.so" }) with CID 2052, state is STARTING.
	[2023-07-07T14:50:43.420766770+09:00 INFO crosvm] crosvm started.
	[2023-07-07T14:50:43.422545090+09:00 INFO crosvm] CLI arguments parsed.
	[2023-07-07T14:50:43.440984015+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/49
	[2023-07-07T14:50:43.441730922+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/54
	[2023-07-07T14:50:43.462055141+09:00 INFO crosvm::crosvm::sys::unix::device_helpers] Trying to attach block device: /proc/self/fd/63
	[WARN] Config entry DebugPolicy uses non-zero offset with zero size
	[WARN] Config entry DebugPolicy uses non-zero offset with zero size
	[INFO] pVM firmware
	avb_slot_verify.c:443: ERROR: initrd_normal: Hash of data does not match digest in descriptor.
	[INFO] device features: SEG_MAX \| RO \| BLK_SIZE \| RING_EVENT_IDX \| VERSION_1 \| ACCESS_PLATFORM
	[INFO] config: 0x201a000
	[INFO] found a block device of size 50816KB
	[INFO] device features: SEG_MAX \| BLK_SIZE \| FLUSH \| DISCARD \| WRITE_ZEROES \| RING_EVENT_IDX \| VERSION_1 \| ACCESS_PLATFORM
	[INFO] config: 0x2022000
	[INFO] found a block device of size 10304KB
	[INFO] No debug policy found.
	[INFO] Starting payload...
	<omitted>
	07-07 05:52:01.322 69 69 I vm_payload: vm_payload: Notified host payload ready successfully
	07-07 05:52:01.364 70 70 I adbd : persist.adb.watchdog set to ''
	07-07 05:52:01.364 70 70 I adbd : persist.sys.test_harness set to ''
	07-07 05:52:01.365 70 70 I adbd : adb watchdog timeout set to 600 seconds
	07-07 05:52:01.366 70 70 I adbd : Setup mdns on port= 5555
	07-07 05:52:01.366 70 70 I adbd : adbd listening on vsock:5555
	07-07 05:52:01.366 70 70 I adbd : adbd started
	#
	```

	The `--auto-connect` option provides you an adb-shell connection to the VM. The
	shell promot (`#`) at the end of the log is for that.

	## Step 5: Run tests

	There are various tests that spawn guest VMs and check different aspects of the
	architecture. They all can run via `atest`.

	```shell
	atest MicrodroidHostTestCases
	atest MicrodroidTestApp
	```

	If you run into problems, inspect the logs produced by `atest`. Their location
	is printed at the end. The `host_log_*.zip` file should contain the output of
	individual commands as well as VM logs.