board/qemu/aarch64-ebbr/readme.txt

Introduction
============

The qemu_aarch64_ebbr_defconfig is meant to illustrate some aspects of the Arm
EBBR specification[1] and the Arm SystemReady IR[2] compliance program.
It allows building an AArch64 U-Boot based firmware implementing the subset of
UEFI defined by EBBR, as well as a Linux OS disk image booting with UEFI, to run
on Qemu.

Building
========

  $ make qemu_aarch64_ebbr_defconfig
  $ make

Generated files under output/images:

* flash.bin: A firmware image comprising TF-A, OP-TEE and the U-Boot bootloader.

* disk.img: An OS disk image comprising the GRUB bootloader, the Linux kernel
  and the root filesystem.

Running under Qemu
==================

Run the emulation with:

  qemu-system-aarch64 \
      -M virt,secure=on,acpi=off \
      -bios output/images/flash.bin \
      -cpu cortex-a53 \
      -device virtio-blk-device,drive=hd0 \
      -device virtio-net-device,netdev=eth0 \
      -device virtio-rng-device,rng=rng0 \
      -drive file=output/images/disk.img,if=none,format=raw,id=hd0 \
      -m 2048 \
      -netdev user,id=eth0 \
      -nographic \
      -object rng-random,filename=/dev/urandom,id=rng0 \
      -rtc base=utc,clock=host \
      -smp 2 # qemu_aarch64_ebbr_defconfig

The login prompt will appear in the terminal that started Qemu.

Using the EBBR firmware to run another OS under Qemu
----------------------------------------------------

It is possible to use the generated firmware binary to install or run another OS
supporting the EBBR specification.

To run another OS on emulation using a live or pre-installed image, use the same
Qemu command line as for the generated OS but adapt the OS image path in the
-drive stanza.
The image generated by the aarch64_efi_defconfig or the Arm ACS-IR images[3] are
examples of pre-installed OS images.

To install another OS using an installer iso image, prepare a destination disk
image first with:

  qemu-img create -f qcow2 disk.qcow2 10G

Then run the OS installer iso image on emulation with:

  qemu-system-aarch64 \
      -M virt,secure=on,acpi=off \
      -bios output/images/flash.bin \
      -cpu cortex-a53 \
      -device virtio-blk-device,drive=hd1 \
      -device virtio-blk-device,drive=hd0 \
      -device virtio-net-device,netdev=eth0 \
      -device virtio-rng-device,rng=rng0 \
      -drive file=<iso>,if=none,format=raw,readonly=on,id=hd0 \
      -drive file=disk.qcow2,if=none,id=hd1 \
      -m 2048 \
      -netdev user,id=eth0 \
      -nographic \
      -object rng-random,filename=/dev/urandom,id=rng0 \
      -rtc base=utc,clock=host \
      -smp 2

The installation medium will show up under the Linux OS installer as /dev/vda
and the destination disk as /dev/vdb.
To reboot into the installed OS, use the same Qemu command line as for the
installation, but without the two stanzas
referring to hd0.
Linux distributions such as Debian, Fedora, openSUSE or Ubuntu provide an OS
installer iso image.

Miscellaneous
=============

This configuration is inspired by the qemu_aarch64_virt_defconfig, the
aarch64_efi_defconfig and the Arm SystemReady IR IoT Integration, Test, and
Certification Guide[4].

Firmware update is currently not supported.

[1]: https://github.com/ARM-software/ebbr
[2]: https://developer.arm.com/Architectures/Arm%20SystemReady%20IR
[3]: https://github.com/ARM-software/arm-systemready/tree/main/IR/prebuilt_images
[4]: https://developer.arm.com/documentation/DUI1101/latest/