arm64

Important

If using QEMU versions < 9.0, replace -machine acpi=off with -no-acpi

Artifacts:

Important

If you are using a prebuilt Target, your artifacts may begin with lmp-base-console-image instead.

└── arm64
    ├── lmp-factory-image-qemuarm64-secureboot.wic.gz
    └── flash.bin

Booting in QEMU

Important

These instructions require QEMU 5.2 or later.

  1. List available Targets and decide on which to boot:

    fioctl targets list

Note

Make sure to set the FIOCTL_FACTORY environment variable so that you can list the target of the specified factory:

export FIOCTL_FACTORY=<factory>

  1. Make a directory for the artifacts and cd into it:

    mkdir -p lmp-qemu/arm64
cd lmp-qemu/arm64

  2. Download the artifacts needed for arm64. These can be found under the Targets tab for your Factory.

  3. Optional. Create and resize a qcow2 image:

    qemu-img create -f qcow2 -F raw -b lmp-factory-image-qemuarm64-secureboot.wic qemuarm64-secureboot_device1.qcow2
qemu-img resize -f qcow2 qemuarm64-secureboot_device1.qcow2 8G

    The above example creates and then resizes to 8G—set to meet your needs.

  4. The directory tree should now look like this:

    lmp-qemu/
└── arm64
    ├── lmp-factory-image-qemuarm64-secureboot.wic
    ├── qemuarm64-secureboot_device1.qcow2 # optional, needed if resizing is required
    └── flash.bin

  5. Run the QEMU script below against the artifacts inside of lmp-qemu/. You can save this as run.sh inside the directory for convenience.

Important

Use .qcow2 if you wish to change the QEMU disk size, or if you are looking to emulate multiple devices. Each image converted and subsequently run with QEMU will be recognized as a distinct device. If you are using the qcow2 image, change the script so that:

  • file= is set as the qcow2 image name, i.e., qemuarm64-secureboot_device1.qcow2
  • format=raw is replaced with format=qcow2.

For example, replacing MACHINE appropriately:

qemu-system-aarch64 -m 1024 -cpu cortex-a57 -no-acpi -bios flash.bin \
-device virtio-net-device,netdev=net0,mac=52:54:00:12:35:02 -device virtio-serial-device \
-drive id=disk0,file=|MACHINE|_device1.qcow2,if=none,format=qcow2 \
-device virtio-blk-device,drive=disk0 -netdev user,id=net0,hostfwd=tcp::2222-:22 \
-object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0 \
-chardev null,id=virtcon -machine virt,secure=on -nographic

Note

The QEMU CLI passes the necessary flags and parameters to the appropriate qemu-system command. This includes path to the image, CPU, network, and other device information. For specifics, consult QEMU’s Documentation.

Booting Graphically

This section shows how to boot QEMU with an OpenGL capable virtual GPU—required for Wayland/Weston. To check the available options for your system, use the -display help flag:

$ qemu-system-aarch64 -display help
Available display backend types:
none
curses
cocoa
dbus

In general, adding the following flags to the QEMU CLI should work:

-display gtk,gl=on -device virtio-gpu-pci

Also, do not copy the -nographic flag at the end of the QEMU CLI below.

Note

You can also utilize the option -display default. This attempts to use the default display type corresponding to the operating system on which you are running the command.

Important

Specifying display options in QEMU does not make console-only images graphical. It just opens a potential graphical output window; interaction remains text-based. Images created with DISTRO=lmp-xwayland or DISTRO=lmp-wayland have graphical interfaces. For further information see: LmP Wayland and LmP XWayland.

If you are following Flashing Your Device and downloading the console image, it will not boot with a graphical interface. See Customizing the Distro to know how to build a new Target image. Ensure that you download the image with the interface, which is usually prefixed with lmp-factory-image.

Compatibility of the display options may vary, and not all options are supported on every host OS. Refer to the QEMU Documentation for more advanced configurations and options.

QEMU CLI

qemu-system-aarch64 -m 1024 -cpu cortex-a57 -machine acpi=off -bios flash.bin \
   -device virtio-net-device,netdev=net0,mac=52:54:00:12:35:02 -device virtio-serial-device \
   -drive id=disk0,file=lmp-factory-image-qemuarm64-secureboot.wic,if=none,format=raw \
   -device virtio-blk-device,drive=disk0 -netdev user,id=net0,hostfwd=tcp::2222-:22 \
   -object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0 \
   -chardev null,id=virtcon -machine virt,secure=on -nographic

Note

A flash.bin artifact is usally in the same location where you downloaded the .wic.gz image. If you are unable to locate flash.bin, consider checking for other artifacts such as QEMU_EFI.fd and QEMU_VARS.fd. Use these to boot the image with the -drive flag. Example:

qemu-system-aarch64 \
-drive file=lmp-factory-image-qemuarm64-secureboot.wic.qcow2,if=virtio,format=qcow2 \
-device qemu-xhci \
-device usb-tablet \
-device usb-kbd \
-net nic \
-net user \
-machine virt \
-cpu host \
-smp 4 \
-m 2048 \
-accel hvf \
-no-reboot \
-device virtio-gpu-pci \
-display default,show-cursor=on \
-drive file=QEMU_EFI.fd,format=raw,readonly=on,if=pflash \
-serial mon:stdio -serial null

Hint

To access QEMU via SSH, append these parameters to the QEMU CLI command above:

-netdev user,id=net0,hostfwd=tcp::2222-:22

Then, run SSH with:

ssh -p 2222 fio@localhost

Tip

You can register your device by following the steps from Registering Your Device.