************************
Using U-Boot as Firmware
************************

U-boot can be configured to support the EBBR specification. This can be
enabled by enabling both `CONFIG_EFI_LOADER` and
`CONFIG_EFI_EBBR_2_0_CONFORMANCE`.

As UEFI Secure Boot is optional in EBBR, that has to be activated seperatly with
`CONFIG_EFI_SECURE_BOOT`

.. graphviz:: bootflow-uboot.dot

UEFI Secure Boot
================

CoreOS build system bundle all the needed public key for secure boot inside the
u-boot binary at buildtime. UEFI variables needed by secure boot are not allowed
to be changed at runtime.

Device tree handling
====================

As per the EBBR specification, the firmware is responsible to provide the
device tree to the kernel.

This means that loading the main device tree and all the device tree overlay are
is the responsibility of the firmware.

.. graphviz:: uboot-dts-handling.dot

Features to implement per machine
=================================

The u-boot provided by CoreOS should implement the following features for each
supported machine:

board_fit_config_name_match
----------------------------

This allows u-boot to select the device tree to use dynamically using board
detection. See `README.multi-dtb-fit`


extension_board_scan
--------------------

The extension_board_scan function has to be implemented. This function should
return the list of add-ons board detected, with the filename of the
correspondig device-tree overlay.

DT Fixup
--------

U-Boot can create, modify and remove node from the device tree dynamically
before starting the kernel. This can be used to pass dynamic information stored
inside a "board descriptor" eeprom or CPLD to the Kernel.

Custom Features that are generic
================================

The u-boot provided by CoreOS should implement the following custom features:

File authentication
-------------------

In order to be able to authenticate device tree, device-tree overlay file or
other file needed by the firmware, we need a command to authenticate a file that
was previously loaded is the `load` command. 

.. note::

    My proposal is to use the UEFI Capsule format, to reuse theses function from
    u-boot:

    - **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
      certificate built into u-boot
    - **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
      content of an authenticated capsule.
    
    An UEFI Capsule is a generic container that can be signed using a x.509
    private key. The public key is stored inside u-boot (it's not the same as
    the keys used for UEFI secure-boot). See
    https://u-boot.readthedocs.io/en/v2022.10/develop/uefi/uefi.html?highlight=capsule#enabling-capsule-authentication


extension_overlay_cmd
---------------------

A custom command should be made for `extension_overlay_cmd`. The extension
subsystem use the command defined as extension_overlay_cmd to load
the overlay `${extension_overlay_name}` into `extension_overlay_addr`

This should reuse the file authentication mechanismus.

.. note::

    A concept on where and how to securly store device tree and overlay needed
    by the kernel has to be written.
    
    My proposal is to use the UEFI Capsule format, to reuse theses function from
    u-boot:

    - **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
      certificate built into u-boot
    - **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
      content of an authenticated capsule.