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

The arm_fvp_ebbr_defconfig is meant to illustrate some aspects of the Arm EBBR
specification[1] and the Arm SystemReady Devicetree band[2].
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 the Arm A-Profile Base RevC AEM FVP.

Building
========

  $ make arm_fvp_ebbr_defconfig
  $ make

Generated files under output/images:

* bl1.bin: A ROM image built from TF-A.
* fip.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 on the FVP
==================

Download the FVP from one of the following sources, corresponding to your host
computer:

- https://developer.arm.com/-/cdn-downloads/permalink/FVPs-Architecture/FM-11.30/FVP_Base_RevC-2xAEMvA_11.30_27_Linux64.tgz
- https://developer.arm.com/-/cdn-downloads/permalink/FVPs-Architecture/FM-11.30/FVP_Base_RevC-2xAEMvA_11.30_27_Linux64_armv8l.tgz

The FVP will be located under one of the corresponding folders:

- Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3
- Base_RevC_AEMvA_pkg/models/Linux64_armv8l_GCC-9.3

Run the simulation with:

  FVP_Base_RevC-2xAEMvA \
      --config-file board/arm/fvp-ebbr/fvp-config.txt \
      -C bp.secureflashloader.fname="output/images/bl1.bin" \
      -C bp.flashloader0.fname="output/images/fip.bin" \
      -C bp.virtioblockdevice.image_path="output/images/disk.img"

The login prompt will appear in a new X terminal.

Using the EBBR firmware to run another OS on the FVP
----------------------------------------------------

It is possible to use the generated firmware binaries to run another OS
supporting the EBBR specification.

To run another OS on simulation using a live or pre-installed image, use the
same FVP command line as for the generated OS but adapt the OS image path in the
virtioblockdevice stanza.
The image generated by the aarch64_efi_defconfig or the Arm ACS Devicetree
images[3] are examples of pre-installed OS images.
Linux distributions such as Debian, Fedora, openSUSE or Ubuntu, or FreeBSD
provide live or pre-installed OS image.

Firmware details
================

Noteworthy firmware features:

- TF-A, OP-TEE & U-Boot
- UEFI, with EFI variables stored on disk in the ESP
- Support for ethernet, RTC and LCD

Architecture diagram:

                 Non-Secure          :   Secure
                                     :
       +---------------------------+ :
  EL0  |          Busybox          | :
       +---------------------------+ : +--------+
  EL1  |           Linux           | : | OP-TEE |  S-EL1
       +---------------------------+ : +--------+
  EL2  | U-Boot, GRUB, Linux (kvm) | :
       +---------------------------+ :
  ...................................:
       +----------------------------------------+
       |                   TF-A                 |  EL3
       +----------------------------------------+

Boot flow:

  TF-A -+-> OP-TEE
        `-> U-Boot -> GRUB -> Linux -> Busybox

TF-A BL1 loads the fit image with the remaining pieces of TF-A, OP-TEE and
U-Boot.
OP-TEE boots, calls back TF-A to go to normal world.
U-Boot loads GRUB with UEFI, boots Linux at EL2.

In this configuration, the Devicetree is static and fully contained in TF-A.

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

This configuration is inspired by the arm_foundationv8_defconfig, the
qemu_aarch64_virt_defconfig and the Arm SystemReady Devicetree Band Integration
and Testing Guide[4].

Firmware update, GOP, MMC and RNG are currently not supported.

[1] https://github.com/ARM-software/ebbr
[2] https://www.arm.com/architecture/system-architectures/systemready-compliance-program/systemready-devicetree-band
[3] https://github.com/ARM-software/arm-systemready/tree/main/SystemReady-devicetree-band/prebuilt_images
[4] https://developer.arm.com/documentation/DUI1101/latest/
