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 a 6device which boots the kernel in EL2 and the kernel was built with KVM enabled. Unfortunately at the 7moment, we don't have an arm64 device in AOSP which does that. Instead, use cuttlefish which 8provides the same functionalities except that the virtual machines are not protected from the host 9(i.e. Android). This however should be enough for functional testing. 10 11We support the following device: 12 13* aosp_cf_x86_64_phone (Cuttlefish a.k.a. Cloud Android) 14 15Building Cuttlefish 16 17```shell 18source build/envsetup.sh 19lunch aosp_cf_x86_64_phone-userdebug 20m 21``` 22 23Run Cuttlefish locally by 24 25```shell 26acloud create --local-instance --local-image 27``` 28 29## Running demo app 30 31The instruction is [here](../../demo/README.md). 32 33## Running tests 34 35There are various tests that spawn guest VMs and check different aspects of the architecture. They 36all can run via `atest`. 37 38```shell 39atest VirtualizationTestCases.64 40atest MicrodroidHostTestCases 41atest MicrodroidTestApp 42``` 43 44If you run into problems, inspect the logs produced by `atest`. Their location is printed at the 45end. The `host_log_*.zip` file should contain the output of individual commands as well as VM logs. 46 47## Spawning your own VMs with custom kernel 48 49You can spawn your own VMs by passing a JSON config file to the VirtualizationService via the `vm` 50tool on a rooted KVM-enabled device. If your device is attached over ADB, you can run: 51 52```shell 53cat > vm_config.json 54{ 55 "kernel": "/data/local/tmp/kernel", 56 "initrd": "/data/local/tmp/ramdisk", 57 "params": "rdinit=/bin/init" 58} 59adb root 60adb push <kernel> /data/local/tmp/kernel 61adb push <ramdisk> /data/local/tmp/ramdisk 62adb push vm_config.json /data/local/tmp/vm_config.json 63adb shell "start virtualizationservice" 64adb shell "/apex/com.android.virt/bin/vm run /data/local/tmp/vm_config.json" 65``` 66 67The `vm` command also has other subcommands for debugging; run `/apex/com.android.virt/bin/vm help` 68for details. 69 70## Spawning your own VMs with Microdroid 71 72[Microdroid](../../microdroid/README.md) is a lightweight version of Android that is intended to run 73on pVM. You can manually run the demo app on top of Microdroid as follows: 74 75```shell 76TARGET_BUILD_APPS=MicrodroidDemoApp m apps_only dist 77adb shell mkdir -p /data/local/tmp/virt 78adb push out/dist/MicrodroidDemoApp.apk /data/local/tmp/virt/ 79adb shell /apex/com.android.virt/bin/vm run-app \ 80 --debug full \ 81 /data/local/tmp/virt/MicrodroidDemoApp.apk \ 82 /data/local/tmp/virt/MicrodroidDemoApp.apk.idsig \ 83 /data/local/tmp/virt/instance.img assets/vm_config.json 84``` 85 86## Building and updating CrosVM and VirtualizationService {#building-and-updating} 87 88You can update CrosVM and the VirtualizationService by updating the `com.android.virt` APEX instead 89of rebuilding the entire image. 90 91```shell 92banchan com.android.virt aosp_arm64 // or aosp_x86_64 if the device is cuttlefish 93UNBUNDLED_BUILD_SDKS_FROM_SOURCE=true m apps_only dist 94adb install out/dist/com.android.virt.apex 95adb reboot 96``` 97 98## Building and updating GKI inside Microdroid 99 100Checkout the Android common kernel and build it following the [official 101guideline](https://source.android.com/setup/build/building-kernels). 102 103```shell 104mkdir android-kernel && cd android-kernel 105repo init -u https://android.googlesource.com/kernel/manifest -b common-android12-5.10 106repo sync 107FAST_BUILD=1 DIST_DIR=out/dist BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh -j80 108``` 109 110Replace `build.config.gki.aarch64` with `build.config.gki.x86_64` if building 111for x86. 112 113Then copy the built kernel to the Android source tree. 114 115``` 116cp out/dist/Image <android_root>/kernel/prebuilts/5.10/arm64/kernel-5.10 117``` 118 119Finally rebuild the `com.android.virt` APEX and install it by following the 120steps shown in [Building and updating Crosvm and 121Virtualization](#building-and-updating). 122