VirtualizationService

VirtualizationService manages multiple guest VMs, protected or otherwise, running on an Android system, primarily by managing instances of crosvm. VirtualizationService exposes an AIDL API, which system services or apps can use to start, monitor, and stop VMs. To use VirtualizationService, execute virtmgr directly or import javalib or rustlib which executes virtmgr as a child process.

VM lifecycle

Access to a VM is tracked by the IVirtualMachine object. As long as there's at least one reference to IVirtualMachine object then the VM continues to run (unless it crashes or shuts down of its own accord). If all references to the IVirtualMachine object are dropped before the VM shuts down, then VirtualizationService automatically shuts down the VM. This process implies that if the client that started the VM is shut down by the low memory killer, then the VM is also shut down, thus preventing resource leaks.

Each VM is managed by its own instance of crosvm, which VirtualizationService in turn manages on behalf of the client. VirtualizationService in virtmgr starts these crosvm child processes as required with allocated global resources including the CID granted by VirtualizationServiceInternal in virtualizationservice, and passes them the file descriptors for the images the VM needs. VirtualizationService then monitors the child process for when they die, so it can notify any remaining clients accordingly.

VM packaging

crosvm supports two different ways of booting a VM: either a kernel and initrd are provided or a bootloader is provided. In either case, an arbitrary number of disk images can also be provided, which might be either a raw image or a composite of several partitions. The various images are provided by the client as file descriptors.

VirtualizationService builds composite disk images on demand. This process is necessary because the composite disk file refers internally to the various partition image files composing the disk, which are passed by the client and might not be directly accessible by crosvm. To get around this issue, VirtualizationService ensures that the file descriptor numbers inherited by crosvm are the same as the file descriptor numbers which VirtualizationService used in creating the composite images. The composite disk image uses filenames in the form to /proc/self/fd/N to represent each partition file.

For Microdroid pVMs, AVF includes a bootloader, which loads the kernel from a partition of a composite disk image, following the standard Android Verified Boot flow.

VM Sockets (vsock)

The primary interface for communication between pVMs is vsock, a standard virtio socket interface. Each VM is identified by a 32-bit context identifier (CID), which is analogous to an IP address, which VirtualizationServiceInternal assigns to the VM when VirtualizationService creates the VM, and can expose services on whatever port numbers the VM chooses. The CID is unique while the VM is running, but the CID value can be recycled when the VM is terminated and all the IVirtualMachine binder handles to the VM have been dropped.

Debug interface

The vm command is provided for debug purposes. This command lets a developer start a VM from the shell, view its logs, and terminate the VM. With the vm command or other interfaces provided by AVF, a VM can start in either debuggable (FULL) or non-debuggable (NONE) mode. With a debuggable VM, you can see OS-level logs, access the ADB shell, and capture crash-dump or app payload. It's recommended to use a non-debuggable VM in production. For more on the command line tool and other debug interfaces that AVF provides, see debug/README.md.