shredos.x86_64

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

The iot-gate-imx8_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 disk image with a U-Boot based firmware
implementing the subset of UEFI defined by EBBR, as well as a Linux OS booting
with UEFI, to run on the Compulab IOT-GATE-iMX8. [3]

This configuration is not related with the official BSP from Compulab. [4]

Building
========

  $ make iot-gate-imx8_ebbr_defconfig
  $ make

Generated files under output/images/:

* disk.img: An eMMC or USB key disk image comprising TF-A, OP-TEE, the U-Boot
  bootloader, the GRUB bootloader, the Linux kernel and the root filesystem.

* flash.bin: A firmware image suitable for flashing in eMMC boot partition
  comprising TF-A, OP-TEE and the U-Boot bootloader.

Running
=======

Before flashing the firmware to eMMC, make sure that you have the IOTG-ACC-M2SD
M.2 to SD adapter for recovery and prepare a recovery SD card. [5]
Insert the SD card and the M.2 adapter.

Prepare a USB key on a PC:

  # dd if=output/images/disk.img of=<USB key device> ; sync

Insert the USB key, close jumper E1 on the board to select recovery boot,
connect to the UART console on the micro USB connector (a Silicon Labs CP2104
UART bridge) with baudrate 115200, power on the board and break to U-Boot
prompt.

Flash the firmware from the USB key to the eMMC boot partition:

  u-boot=> usb start
  u-boot=> usb dev 0
  u-boot=> usb read ${loadaddr} 0x42 0x1fbe
  u-boot=> mmc dev 2 1
  u-boot=> mmc write ${loadaddr} 0x42 0x1fbe
  u-boot=> mmc partconf 2 0 1 0

Power off the board, remove jumper E1 and the M.2 SD card adapter, then restart
the board; it should boot to Linux, with the root filesystem on the USB key.

Other setups are also possible, with the firmware and/or the root filesystem in
the eMMC user data. The firmware binary is also available as flash.bin for
convenience, to allow network download for example.

With the firmware in the eMMC boot partition, it is possible to install or run
another OS supporting the EBBR specification.

The image generated by the aarch64_efi_defconfig, the images from Linux
distributions such as Debian, Fedora, openSUSE, Ubuntu, OpenWrt and Yocto, and
the Arm ACS Devicetree images[6] are examples of compatible OS images.

When installing other OSes to eMMC, it is recommended to protect the first 32KB
of the user data with a partition, as this is where the U-Boot environment can
be saved.

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

Noteworthy firmware features:

- TF-A, OP-TEE & U-Boot
- UEFI, with EFI variables stored on disk in the ESP
- Support for ethernet, USB and RTC
- U-Boot environment in eMMC user data (starting from byte 0x4400)

Architecture diagram:

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

Boot flow:

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

The ROM loads U-Boot SPL.
U-Boot SPL does the DRAM setup, loads the fit image with TF-A, OP-TEE, U-Boot
and the Devicetree.
In this configuration TF-A is booting with BL2 and BL31.
OP-TEE amends the Devicetree, calls back TF-A to go to normal world.
U-Boot loads GRUB with UEFI, boots Linux at EL2.

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

This configuration is based on the work of Paul Liu[7] and is inspired by the
other configurations related with EBBR, and the Arm SystemReady Devicetree Band
Integration and Testing Guide[8].

To avoid a circular build dependency, we skip the binman step during U-Boot
build:

  BR2_TARGET_UBOOT_CUSTOM_MAKEOPTS="cmd_binman=:"

Then we run binman manually in the post-image script.

Firmware update and UEFI Secure Boot are currently not supported.
The disk image cannot be used for SD card recovery at this point.

[1] https://github.com/ARM-software/ebbr
[2] https://www.arm.com/architecture/system-architectures/systemready-compliance-program/systemready-devicetree-band
[3] https://www.compulab.com/products/iot-gateways/iot-gate-imx8-industrial-arm-iot-gateway/
[4] https://mediawiki.compulab.com/w/index.php?title=Building_IOT-GATE-iMX8_and_SBC-IOT-iMX8_Yocto_Linux_images
[5] https://mediawiki.compulab.com/w/index.php?title=IOT-GATE-iMX8_and_SBC-IOT-iMX8:_U-Boot:_Recovery
[6] https://github.com/ARM-software/arm-systemready/tree/main/SystemReady-devicetree-band/prebuilt_images
[7] https://git.linaro.org/plugins/gitiles/people/paul.liu/systemready/build-scripts
[8] https://developer.arm.com/documentation/DUI1101/latest/