1# Getting started with Protected Virtual Machines
2
3## Prepare a device
4
5First you will need a device that is capable of running virtual machines. On arm64, this means
6a device which boots the kernel in EL2 and the kernel was built with KVM enabled.
7
8Here are instructions for select devices:
9
10 * [yukawa: Khadas VIM3L](yukawa.md) (arm64)
11 * [goldfish: Android Emulator](goldfish.md) (x86_64)
12
13## Running tests
14
15Virtualization source code and relevant tests are located in
16[packages/modules/Virtualization](https://android.googlesource.com/platform/packages/modules/Virtualization)
17of the AOSP repository.
18
19### Device-side tests
20
21The tests spawn guest VMs and test different aspects of the architecture.
22
23You can build and run them with:
24
25```shell
26atest VirtualizationTestCases
27```
28
29If you run into problems, inspect the logs produced by `atest`. Their location is printed at the
30end. The `host_log_*.zip` file should contain the output of individual commands as well as VM logs.
31
32## CrosVM
33
34[CrosVM](https://android.googlesource.com/platform/external/crosvm/) is a Rust-based Virtual Machine
35Monitor (VMM) originally built for ChromeOS and ported to Android.
36
37It is not installed in regular Android builds (yet!), but it's installed in the VIM3L (yukawa)
38build, as part of the `com.android.virt` APEX.
39
40### Spawning your own VMs
41
42You can spawn your own VMs by passing a JSON config file to the Virt Manager via the `vm` tool on a
43rooted KVM-enabled device. If your device is attached over ADB, you can run:
44
45```shell
46$ cat > vm_config.json
47{
48  "kernel": "/data/local/tmp/kernel",
49  "initrd": "/data/local/tmp/ramdisk",
50  "params": "rdinit=/bin/init"
51}
52$ adb root
53$ adb push <kernel> /data/local/tmp/kernel
54$ adb push <ramdisk> /data/local/tmp/ramdisk
55$ adb push vm_config.json /data/local/tmp/vm_config.json
56$ adb shell "start virtmanager"
57$ adb shell "/apex/com.android.virt/bin/vm run /data/local/tmp/vm_config.json"
58```
59
60The `vm` command also has other subcommands for debugging; run `/apex/com.android.virt/bin/vm help`
61for details.
62
63### Building and updating CrosVM and Virt Manager
64
65You can update CrosVM and the Virt Manager service by updating the `com.android.virt` APEX. If your
66device already has `com.android.virt` (e.g. VIM3L):
67
68```shell
69$ TARGET_BUILD_APPS="com.android.virt" m
70$ adb install $ANDROID_PRODUCT_OUT/system/apex/com.android.virt.apex
71$ adb reboot
72```
73
74If it doesn't have the APEX yet, you first need to place it manually to the
75system partition.
76
77```shell
78$ adb root
79$ adb disable-verity
80$ adb reboot
81$ adb wait-for-device root
82$ adb remount
83$ m com.android.virt
84$ adb sync
85$ adb reboot
86```
87
88Once the APEX is in `/system/apex`, you can use `adb install` to update it
89further.
90