.. include:: /keyword.rst

===================================
|IOT-YOCTO| BSP & Boot Architecture
===================================

This section describes the system booting architecture and the BSP images information at each boot stage.

.. contents:: Sections
    :local:
    :depth: 1

.. toctree::
    :hidden:
    :maxdepth: 2

    ab-part
    part-layout
    secure-boot
    boot-from-external-storage

The BSP(board support package) has the following booting architecture:

.. figure:: /_asset/sw_yocto_boot-bootflow.png
    :align: center
    :width: 900px

    |IOT-YOCTO| BSP Boot Architecture

MediaTek SoC ROM Code
---------------------

The MediaTek SoC ROM code will try to boot from different media:

* eMMC
* USB
* UFS (MT8395 only)

The |IOT-YOCTO| only allows to boot from embedded MultiMedia Card (eMMC) and Universal Flash Storage (UFS).
Universal Serial Bus (USB) is only used as part of the image flashing process but cannot be used alone to
boot to a Linux userspace.

Please refer to the functional block and IoT Yocto support status for hardware features that IoT Yocto enables:

* :ref:`MT8365 (Genio 350) <soc-mt8365>`
* :ref:`MT8370 (Genio 510) <soc-mt8370>`
* :ref:`MT8390 (Genio 700) <soc-mt8390>`
* :ref:`MT8395 (Genio 1200) <soc-mt8395>`

.. _boot-emmc:

EMMC Boot
^^^^^^^^^

When the SoC boots, it chooses which media to boot from. If it chooses eMMC
boot, the boot ROM looks at the first boot partition for a second stage
bootloader.

In case the ROM code fails to find a valid boot partition or valid second
stage bootloader, it will automatically go into :ref:`sw/yocto/boot:USB Boot`.

.. _boot-g1200-ufs:

UFS Boot
^^^^^^^^

MT8395 provides support to boot from UFS storage. However, the prebuilt |G1200-EVK| image
does not provide such support because |G1200-EVK-REF-BOARD| does not have UFS storage.

Please refer to the ``mt8395-evb-ufs`` in
`meta-mediate-bsp layer <https://gitlab.com/mediatek/aiot/rity/meta-mediatek-bsp/-/blob/dunfell/conf/machine/mt8395-evb-ufs.conf>`_
to know how to configure for UFS booting.


USB Boot
^^^^^^^^

In |IOT-YOCTO|, the ROM code USB boot is used only for flashing.


BL2 (TF-A)
----------

The second stage bootloader is based on `Trusted Firmware A (TF-A) <https://www.trustedfirmware.org/projects/tf-a/>`_.
The |IOT-YOCTO| BSP ships pre-built binaries for second stage bootloaders.

We base the second stage bootloader on `Trusted Firmware A (TF-A) <https://www.trustedfirmware.org/projects/tf-a/>`_.
|IOT-YOCTO| BSP includes pre-built binaries for second stage bootloaders.

BL2 first initializes the hardware:

* Initialize the system timer
* Initialize and turn on the phase locked loops (PLLs)
* Initialize the Power Management IC (PMIC) wrap component in order to be able to talk to the PMIC
* Sends a `baseband power-up` signal to the PMIC to notify him of a successful power up.
* Initialize the Double Data Rate (DDR) SDRAM
* Initialize the eMMC

Once BL2 initializes the hardware, it will read 4MB of memory from the `bootloaders` partition
of the eMMC. You can retrieve the offset of the `bootloaders` partition using the TF-A
application programming interface (API) :code:`get_partition_entry(partition_name)`.
The API provides the entry of the `bootloaders` partition to find the  ``fip.bin`` file.
This partition section should contain the ``fip.bin`` file.

Firmware Image Package (FIP) is a packaging format used by TF-A to package
firmware images. In |IOT-YOCTO| the FIP contains BL31, BL32, BL33 and optionally
some certificates when secure boot is enabled.

BL2 will read the FIP package and execute each of the binary it contains.

BL31 (TF-A)
-----------

TF-A provides BL31, which provides the `Power State Coordination Interface (PSCI) routines <https://developer.arm.com/architectures/system-architectures/software-standards/psci>`_.
Once the system loads BL33, it no longer uses BL2. However, BL31 remains in
DDR until you power off or reboot.

Once BL31 completes initialization, it will jump back to BL2.

Source repository: https://gitlab.com/mediatek/aiot/bsp/trusted-firmware-a

BL32 (OP-TEE)
-------------

BL32 is the secure OS that runs in `TrustZone <https://developer.arm.com/ip-products/security-ip/trustzone>`_.
|IOT-YOCTO| BSP is using by default `Open Portable Trusted Execution Environment (OP-TEE) <https://www.op-tee.org/>`_ trusted OS.

Like BL31, OP-TEE OS stays in DDR until a power off or a reboot.

Source repository: https://gitlab.com/mediatek/aiot/bsp/optee-os

BL33 (U-Boot)
-------------

U-Boot is the third and last stage bootloader in the |IOT-YOCTO| boot architecture. It
is used to load and boot the kernel from the `kernel` partition.

In |IOT-YOCTO| the kernel must be encapsulated into a Flattened Image Tree (FIT) image.
The FIT image contains the kernel binary, a Device Tree Blob (DTB), and
optionally some Device Tree Blob Overlay (DTBO).

U-Boot uses Device Tree Blob Overlays (DTBOs) to provide optional features to a board, such as cameras,
displays, or any daughter boards. U-Boot checks its :code:`boot_conf`
environment variable to determine which overlay (if any) it should load and
merge with the main DTB. To merge a DTBO, you need to change :code:`boot_conf` using the following format:

.. code-block:: text

        boot_conf=#conf-[platform_dtb_name]#conf-[feature1_dtbo_name]#conf-[feature2_dtbo_name]

For example if you would like to add a DTBO used for Display Serial Interface (DSI) panel support to |G350-EVK| (`dtbo` name: :code:`display-dsi.dtbo`).

.. code-block:: text

        boot_conf=#conf-mediatek_mt8365-evk.dtb#conf-display-dsi.dtbo

There are 2 methods that developers can configure :code:`boot_conf` to merge DTBOs by U-Boot in |IOT-YOCTO|.

1. modify it during the Yocto build system by setting the following variable:

.. code-block::

        KERNEL_DEVICETREE_OVERLAYS_AUTOLOAD += "display-dsi.dtbo"

2. modify it with using `genio-tools`

.. code-block::

        genio-flash --load-dtbo display-dsi.dtbo

Besides, it is possible to set the :code:`boot_conf` variable from the U-Boot shell,
target Linux system, or the `u-boot-initial-env` file directly.
There are several ways to modify :code:`boot_conf`.

* Writing to the :code:`u-boot-initial-env` file presented in the deploy image folder before flashing image.
  (Not recommended because it may be overwritten by Bitbake later on)

* In the U-Boot shell:

.. prompt:: auto, =>

        setenv boot_conf "you-boot-env-var"; saveenv

* In the target Linux system:

.. prompt:: auto, $

        fw_setenv boot_conf "you-boot-env-var"

User can also use U-Boot to flash (via Fastboot), or to boot the kernel and/or
rootfs using a USB connection. Please refer to the board's documentation to
know which features your specific board supports.

Boot from External Storage
^^^^^^^^^^^^^^^^^^^^^^^^^^

In MediaTek's |IOT-YOCTO| platforms, the Boot ROM (BROM) **dose not** natively support booting from removable storage types such as USB, SD Card, or Ethernet.
BROM supports only main storage like eMMC or UFS, depends on the hardware capability of each Genio platforms.
However, it is still possible to boot Linux from these storage types by leveraging the common features provided by U-Boot (BL33).
For more detail, please refer to :doc:`Boot from External Storage </sw/yocto/boot-from-external-storage>` chapter.

Source repository: https://gitlab.com/mediatek/aiot/bsp/u-boot

Linux
-----

The `Linux kernel <https://www.kernel.org/>`_ is the main OS running. It will
load the root filesystem (rootfs) and starts running the `init` process.

The following versions of Linux are currently supported on |IOT-YOCTO|:

.. csv-table:: Kernel Version and Branches
   :header: "Kernel version", "Branch name"
   :widths: 15, 15

   "v5.4", ``mtk-v5.4``
   "v5.10", ``mtk-v5.10``
   "v5.15", ``mtk-v5.15-dev``

By default, the system builds the latest stable Linux release supported by |IOT-YOCTO|.
If you want to use an older supported kernel, set the :code:`PREFERRED_VERSION_linux-mtk`
variable in your `local.conf`.

For example if you want to use the v5.4 branch you can set:

.. code-block::

        PREFERRED_VERSION_linux-mtk = "5.4%"