.. include:: /keyword.rst

======================
Modifying Board Assets
======================

The booting procedure of the Genio platform consists of several stages, and each stage
is implemented by different software component, which is described in :doc:`/sw/yocto/boot`.

The following sections will walk you through the process to modify these software components
and flash board assets to the target board for testing.

.. important::

    Before proceeding, please ensure that you have downloaded |IOT-YOCTO| source tree
    and built an image from it. Please refer to :doc:`/sw/yocto/get-started/build-code`
    for more information.

.. note::

    The document will take U-Boot as an example to demonstrate how to check out,
    modify, and build the source tree. The same procedure applies to other components.

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


Modifying U-Boot
================

To modify the U-Boot source tree, please use `Yocto devtool <https://docs.yoctoproject.org/ref-manual/devtool-reference.html>`_ to check out the source tree specified by the recipe:

.. prompt:: bash

    MACHINE=<board-name> devtool modify u-boot

After running the command, the checked out source tree will be located under the path
``<BUILD_DIR>/workspace/sources/u-boot``.

.. warning::

    While it may appear to work if you modify the source code files under the ``<BUILD_DIR>/tmp/work``
    directories,
    this breaks Yocto's build cache management logic, and your changes may be overwritten by
    the ``bitbake`` tool without warning. Always use ``devtool`` and modify files under
    ``<BUILD_DIR>/workspace``.

The extracted directory is a git repository, and you can modify the source code and run ``git commit``
to track changes locally. The initial git history created by ``devtool modify`` consists of:

* The git repository commit designated by the ``SRC_URI`` and ``SRCREV`` variables in the recipe.
* Extra patches applied by the Yocto recipe on top of the ``SRCREV`` commit. These patches are
  usually board dependent fixes.

An example of U-Boot commit history shows these commits:

.. image:: /_asset/devtool-git-log-example.png

In the example above, the U-Boot recipe fetches commit ``a5d8f6`` from the U-Boot source repository, and then
applies 4 patches. These patches are the result of two different Yocto layers:

* 1 additional patches in **.bb** file in ``meta-mediatek-bsp``: ``src/meta-mediatek-bsp/recipes-bsp/u-boot/u-boot_git.bb``.
* 3 additional patches in **.bbappend** file in ``meta-rity``: ``src/meta-mediatek-bsp/recipes-bsp/u-boot/u-boot_git.bbappend``

Because of the flexible layered architecture of Yocto, each layer is able to extend or modify settings
of base layers, it is not easy to figure out correctly which git commit to check out, or which
patch to be applied on the source tree.
Therefore, we recommend you to always extract the source tree with ``MACHINE=<board-name> devtool modify``
so that you can get the correct source tree.

.. note::

    Once ``devtool modify <recipe>`` has been executed, patch changes in the recipe files will be
    ignored, because the extracted source repository in workspace overrides configurations in the recipe.

After modifying the source code, you can re-compile it with:

.. prompt:: bash

    MACHINE=<board-name> bitbake u-boot

Since the U-Boot binary is not the final image used for flashing the target board, we need
one more step for generating it:

.. prompt:: bash

    MACHINE=<board-name> bitbake trusted-firmware-a

The built artifact is located in ``<BUILD_DIR>/tmp/deploy/images/<MACHINE>/fip.bin``.

.. important::

    It is not intuitive to determine which recipe used for modifying source tree and
    which recipe used for generating images for flashing the target board. Here is
    the table for listing each component and the corresponding recipes used for
    modification and image generation.

    .. csv-table:: Recipes for modification and image generation
       :file: /_asset/tables/bootloader-recipes.csv
       :header-rows: 1
       :align: center

    Note that since BL31, BL32, BL33 are all bundled in single partition image
    ``fip.bin``, updating the source of any one of them requires rebuilding both the
    recipe for modification and the recipe for image generation.

Once you are satisfied with the modifications, there are two ways for integrating
these changes to the recipe:

* If you are maintaining your own U-Boot git repository, you can commit your changes
  to it, and update the ``SRCREV`` of the corresponding recipe with the
  correct git hash.
* If those changes are small enough, you can create patches, add them to the
  directory containing patches in the Yocto source tree, and update the ``SRC_URI``
  of the corresponding recipe to add your listing of patches.

After finishing the integration, now you can reset the `devtool` environment and
switch to use the updated recipe for building U-Boot:

.. prompt:: bash

    MACHINE=<board-name> devtool reset u-boot

.. note::

    After running ``devtool reset <recipe>``, the workspace folder
    (``<BUILD_DIR>/workspace/sources/u-boot`` in this case) containing
    checked out source tree will be kept. You are free to delete it if you don't
    need it anymore.

Modifying boot assets
=====================

In addition to modifying bootloaders, |IOT-YOCTO| allows the user to add or modify
static data such as boot logos, audio, or video files, which will be stored in
the *bootassets* partition.

To add new data, please create a new file ``bootassets-part.bbappend`` under your
custom layer, with following content:

.. code::

   FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

   SRC_URI += " \
      file://data.bin \
   "

   collect_artifacts:append() {
      cp ${WORKDIR}/data.bin ${BOOTASSETS_IMAGE_FS}
   }

And please run the command to generate boot assets:

.. prompt:: bash

    MACHINE=<board-name> bitbake bootassets-part

The generated image will be in ``<BUILD_DIR>/tmp/deploy/images/<MACHINE>/bootassets.vfat``.

Flashing to target board
========================

After modifying board assets (including bootloader binaries or boot assets), we can
use `genio-flash` tool to flash those images to the target board.
Each partition can be flashed individually without touching others:

.. prompt::

    $ cd <BUILD_DIR>/deploy/images/<MACHINE>/

    # Flash bl2
    $ genio-flash mmc0boot0

    # Flash U-Boot
    $ genio-flash bootloaders

    # Flash U-Boot & U-Boot env
    $ genio-flash bootloaders mmc0boot1

    # Flash boot assets
    $ genio-flash bootassets

The table below lists the needed argument supplied to `genio-flash` for flashing board assets.

.. csv-table:: Partitions and corresponding images for flashing
   :file: /_asset/tables/bootloader-parts.csv
   :header-rows: 1
   :align: center