.. 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: 1

    ab-part
    part-layout
    secure-boot

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 eMMC and UFS. 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 booting the SoC will chose which media to boot from. If the eMMC boot
is chosen, the bootrom will look at the first boot partition to look 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.

BL2 first initializes the hardware:

* Initialize the system timer
* Initialize and turn on the PLLs
* Initialize the 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 DDR
* Initialize the eMMC

Once the hardware is initialized, BL2 will read 4MB of memory stored at `bootloaders` partition
of the eMMC. The offset of `bootloaders` partition can be retrieved by TF-A API
:code:`get_partition_entry(partition_name)`.
The API provide the entry of `bootloaders` partition to find the fip.bin file.
This partition section should contains 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)
-----------

BL31 is provided by TF-A and provides the `PSCI routines <https://developer.arm.com/architectures/system-architectures/software-standards/psci>`_.
Unlike BL2 which won't get used anymore once BL33 is loaded, BL31 will stay
in DDR until a power off or a reboot.

Once BL31 is finished to initialize, 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 `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).

The DTBOs are used to provide optional features to a board, for instance for
cameras, display, or any daughter board. U-Boot looks at its :code:`boot_conf`
environment variable in order to know which (if any) overlay it must load and
merge to the main DTB. To merge a DTBO you need to change :code:`boot_conf` as 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 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"

U-Boot can also be used to flash (via fastboot), or to boot the kernel and/or
rootfs using an USB connection. Please refer to the boards documentation in
order to know which features are supported for your specific board.

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 latest Linux release will be built, if you want to use an older
supported kernel you can 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%"