Note: Virtualization is not actively supported. While basic functionality is intended to work, additional support may be hard to obtain. And feature requests are unlikely to be implemented.
Virtualization is available on Intel devices with VMX enabled and ARMv8.0 and above devices that boot into EL2. The following hardware will have the best availability:
The following hardware is also available, but is more prone to failure:
Some virtualization features will work when using the Fuchsia emulator with nested VMX enabled. Notably, Vulkan acceleration using virtmagma will not be available to any guests when running in the Fuchsia emulator.
While arbitrary Linux guests may run on Fuchsia, the following guest configurations are available out-the-box:
Note: The Debian Guest package expects the Linux kernel binaries and userspace image to be in //prebuilt/virtualization/packages/debian_guest. You should create them before running fx build by following the instructions in debian_guest/README.md. Googlers: You don't need to do this, the prebuilt images are downloaded from CIPD by Jiri.
For each guest operating system, there is a guest manager and a core shard that must be included in the build.
Firstly, enable virtualization by creating a //local/BUILD.gn file in your Fuchsia checkout. In that file, add an assembly override for enabling virtualization:
assembly_developer_overrides("enable_virtualization") {
platform = {
virtualization = {
enabled = true
}
}
}
Next, configure your build for the desired guest. The {{ ‘’ }}PRODUCT{{ ‘’ }} is typically core, and the {{ ‘’ }}BOARD{{ ‘’ }} is typically one of x64, chromebook-x64, sherlock.
{All Guests}
fx set {{ '<var>' }}PRODUCT{{ '</var>' }}.{{ '<var>' }}BOARD{{ '</var>' }} --assembly-override=//local:enable_virtualization --with //src/virtualization/bundles:all_guests
{Debian Guest}
fx set {{ '<var>' }}PRODUCT{{ '</var>' }}.{{ '<var>' }}BOARD{{ '</var>' }} --assembly-override=//local:enable_virtualization --with //src/virtualization/bundles:debian
{Zircon Guest}
fx set {{ '<var>' }}PRODUCT{{ '</var>' }}.{{ '<var>' }}BOARD{{ '</var>' }} --assembly-override=//local:enable_virtualization --with //src/virtualization/bundles:zircon
{Termina Guest}
fx set {{ '<var>' }}PRODUCT{{ '</var>' }}.{{ '<var>' }}BOARD{{ '</var>' }} --assembly-override=//local:enable_virtualization --with //src/virtualization/bundles:termina
Finally, build Fuchsia:
fx build
You can launch a guest using the guest CLI tool. The tool will launch the guest and then provide access to a virtio-console over stdio.
Note: Running a guest via QEMU on x64 requires KVM. You may also need to enable nested KVM on your host machine. For Googlers working on Cloudtop environments, note that you may need a specialist Cloudtop instance for nested virtualization.
Note: The following instructions assume a Linux host machine with an Intel processor. This will not work if your host machine has an AMD processor.
If you are running Fuchsia directly on dedicated hardware (e.g. Sherlock), host configuration is not necessary. However, most Googlers will want to run via QEMU on a host workstation. For this use case, you'll need to check if nested virtualization is enabled with the following command:
cat /sys/module/kvm_intel/parameters/nested
An output of Y indicates nested virtualization is enabled, 0 or N indicates not enabled.
If needed, you can enable nested virtualization until the next reboot:
modprobe -r kvm_intel modprobe kvm_intel nested=1
Or you can make the change permanent by adding options kvm_intel nested=1 to /etc/modprobe.d/kvm.conf.
One you have your host machine setup, you can start the Fuchsia Emulator:
ffx emu start
(fuchsia) $ guest launch debian Starting Debian $ uname -a Linux machina-guest 5.10.0-13-amd64 #1 SMP Debian 5.10.106-1 (2022-03-17) x86_64 GNU/Linux
{# Allow the ‘{{{’ below: #}
{% verbatim %}
(fuchsia) $ guest launch zircon Starting zircon physboot: {{{reset}}} physboot: {{{module:0:physboot:elf:9f2c4d6615bd603d}}} physboot: {{{mmap:0x100000:0x14a100:load:0:rwx:0x0}}} physboot: | Physical memory range | Size | Type physboot: | [0x0000000000008000, 0x0000000000080000) | 480K | free RAM physboot: | [0x0000000000100000, 0x00000000001cd000) | 820K | phys kernel image physboot: | [0x00000000001cd000, 0x000000000024a000) | 500K | free RAM physboot: | [0x000000000024a000, 0x000000000024a100) | 256B | phys kernel image physboot: | [0x000000000024a100, 0x000000000024b000) | 3840B | free RAM …
{# Re-enable variable substitution #}
{% endverbatim %}
(fuchsia) $ guest launch termina Starting Termina …
On products with a UI Stack, the debian and zircon guests will also create a window that displays a virtual framebuffer powered by a virtio-gpu. Input from that window will also be sent to the guest as a virtual keyboard.
Machina has a set of integration tests that launch Zircon and Debian guests to test the VMM, hypervisor, and each of the virtio devices. To run the tests, first add them to your build:
`fx set {{ '<var>' }}PRODUCT{{ '</var>' }}.{{ '<var>' }}BOARD{{ '</var>' }} --with //src/virtualization:tests` fx build
Then run any of the following tests:
# Tests of the low level hypervisor syscalls: $ fx test hypervisor_tests # Basic tests that verify OS boot and basic functionality: $ fx test virtualization-core-tests # Test suites focused on specific devices: $ fx test virtualization-block-tests $ fx test virtualization-net-tests $ fx test virtualization-sound-tests $ fx test virtualization-vsock-tests $ fx test virtualization-gpu-tests $ fx test virtualization-input-tests