Fuchsia

Fuchsia emulator

The Fuchsia emulator (FEMU) is the default emulator for Fuchsia. FEMU allows you to test Fuchsia components and applications without a physical Fuchsia device.

FEMU is included in the Fuchsia source tree. FEMU is downloaded (or updated) by jiri, as part of jiri update or jiri run-hooks, and is fetched into the /prebuilt/third_party/aemu directory of your Fuchsia source tree.

You can launch FEMU using the fx vdl command, or using the fvdl command in the Fuchsia SDK.

FEMU, AEMU, and QEMU

FEMU is based on the Android Emulator (AEMU){:.external}, which is a fork of QEMU{:.external} – in some instances, such as emulating Zircon, you need to use QEMU instead.

Due to legacy issues, there may be references to AEMU in the code and documentation.

Emulating Zircon

If you only want to emulate Zircon, you must use fx qemu instead. Read Debugging the Kernel using QEMU to learn more. This is for kernel developers. Most Fuchsia developers do not need to use this workflow.

Features

FEMU looks and behaves like a Fuchsia device, except that no paving or flashing is required with FEMU.

The features of FEMU include:

  • GUI Support: You can run Fuchsia with the GUI (by default) or without the GUI (using the --headless argument).
  • GPU Support: You can run with the host’s GPU (by default) with full Vulkan{:.exyernal} support, or you can choose software rendering using SwiftShader{:.external}.
  • Remote Development: You can use a remote desktop with FEMU, either with Chrome Remote Desktop or from the command line using fx emu-remote command.

To see full list of supported flags:

fx vdl start --help

The Fuchsia SDK's fvdl command supports the same flags as fx vdl.

Image and board support

When setting up FEMU using fx set, FEMU supports the following boards:

  • qemu-x64
  • qemu-arm64

With the Fuchsia SDK, FEMU supports the following pre-built images:

  • qemu-x64
  • workstation.qemu-x64-release
  • qemu-arm64

ARM64 support (qemu-arm64) is very limited and not recommended.

Networking

On Linux, FEMU should generally be run with the -N flag that provides networking through an emulated NIC.

Note: Instructions for setting up networking for FEMU is in the Start the Fuchsia Emulator guide.

Without -N, your emulator is not discoverable using ffx target list (orfx list-devices). However, you can manually set the SSH address and use fx tools to interact with your emulator.

If starting the emulator without -N (that is, fx vdl start), an available TCP port from the host is picked and forwarded to the emulator's SSH port. When the emulator launches successfully, an additional instruction, which uses fx set-device with the correct SSH port, is printed in the terminal output:

fx set-device 127.0.0.1:{{ '<var>' }}SSH_PORT{{ '</var>' }}

Using ths command above, you can manually set the SSH device.

To verify that your fx tool is using the correct port, run the following command:

fx status

You should see the SSH address printed next to Device name.

To SSH into the emulator, run the following command:

fx ssh

Unsupported CPUs

FEMU currently does not run on:

  • ARM64 processors, including the Apple M1 processor.
  • AMD processors.

Supported hardware for graphics acceleration

FEMU currently supports a limited set of GPUs on macOS and Linux for hardware graphics acceleration. FEMU uses a software renderer fallback for unsupported GPUs.

Common usage

To launch FEMU, complete the Get started with Fuchsia guide.

Alternatively, you can use the Fuchsia SDK and use pre-built system images.

Once you're able to launch FEMU, you can perform the following tasks: