.. include:: /keyword.rst

=================
Yocto Development
=================

If you have completed the :doc:`/sw/yocto/get-started` section, you should now have built a image for your Genio device.  This section aims to provide help and advice to enable you to continue your development journey.

Partial Build
=============

During development, you might want to build a single package instead of the entire image. To do so, use the following commands:

.. code-block:: bash

    $ bitbake <recipe-name>

The `<recipe-name>` is the name of the BitBake recipe of the package you want to build. For example, the Linux kernel is defined
in these recipe `.bb` files:

* ``meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.4.bb``
* ``meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.10.bb``
* ``meta-mediatek-bsp/recipes-kernel/linux/linux-mtk/recipes-kernel/linux/linux-mtk_5.15.bb``

The name of the package is therefore ``linux_mtk``. To only rebuild the kernel instead of the entire ``rity-demo-image``, use the 
following command:

.. code-block:: bash

    $ bitbake linux-mtk

Please note that this only rebuilds the kernel image (``fitImage``), but not the **image** of the entire system (``*.wic.img``). To update the kernel image,
use Yocto `virtual provider <https://docs.yoctoproject.org/4.0.22/dev-manual/new-recipe.html#using-virtual-providers>`_:

.. code-block:: bash

    $ bitbake virtual/kernel

Similarly, if you only want to rebuild bootloader BL2 image (``bl2.img``), you can use:

.. code-block:: bash

    $ bitbake trusted-firmware-a


Similarly, if you only want to rebuild bootloader U-Boot (BL33) image, you can use the commands below and repackage the bootloader BL31/BL32/BL33 image ``fip.bin``:

.. code-block:: bash

    $ bitbake virtual/bootloader
    $ bitbake trusted-firmware-a


.. _machine-name-for-bitbake:

Build for Other Boards
======================

.. warning::

   The boards listed below contains 3rd party boards and boards under development.
   There is no guarantee that these combinations will work out-of-box.

You can use the ``MACHINE`` variable to assign the board you would like to build:

.. prompt:: bash

	DISTRO=rity-demo MACHINE=<machine> bitbake rity-demo-image

The available values for ``<machine>`` can be found in the ``$BUILD_DIR/conf/local.conf`` configuration file. A snip of the file is shown below:

.. code-block::

    # uncomment the line related to the target
	#MACHINE ??= "genio-1200-evk"
	#MACHINE ??= "genio-350-evk"
	#MACHINE ??= "genio-510-evk"
	MACHINE ??= "genio-700-evk"

You can also locate all the reference IoT board recipes in:

``src/meta-mediatek-bsp/conf/machine/``

For example, if the ``.conf`` files in the directory are:

.. code:: text

	genio-1200-evk.conf -> mt8395-evk.conf
	genio-1200-evk-p1v1.conf -> mt8395-evk-p1v1.conf
	genio-1200-evk-ufs.conf -> mt8395-evk-ufs.conf
	genio-350-evk.conf -> mt8365-evk.conf
	genio-510-evk.conf -> mt8370-evk.conf
	genio-700-evk.conf -> mt8390-evk.conf
	mt8183-evb.conf
	mt8183-pumpkin.conf
	mt8365-evk.conf
	mt8365-pumpkin.conf
	mt8365-sb35.conf
	mt8370-evk.conf
	mt8390-evk.conf
	mt8395-evb-ufs.conf
	mt8395-evk.conf
	mt8395-evk-p1v1.conf
	mt8395-evk-ufs.conf
	mt8516-pumpkin.conf

Note that ``genio-1200-evk.conf`` is an alias to ``mt8395-evk.conf``. In this case, the following ``<machine>`` names are available:

* ``genio-1200-evk``
* ``mt8395-evk``

For details, please refer to the `BSP documentation <https://mediatek.gitlab.io/aiot/rity/meta-mediatek-bsp/boards/index.html>`_.


Build Other Images
==================

The :doc:`Get Started guide </sw/yocto/get-started>` made use of the ``rity-demo-image`` image recipe.
There are other recipes in |IOT-YOCTO| that supports different development boards and also different software packages.
The |IOT-YOCTO| bring up image (``rity-bringup-image``) is mostly used for BSP development and board bring up.
This image contains the some tools necessary to validate software and hardware.

``rity-bringup-image`` is designed to be built with the ``DISTRO`` variable set
to the following:

.. code::

	DISTRO=rity-bringup

You can use the following command to build the `rity-bringup-image`:

.. prompt:: bash $

	DISTRO=rity-bringup MACHINE=<machine> bitbake rity-bringup-image

The resulting image is located in

.. code::

    $BUILD_DIR/tmp/deploy/images/<machine>

Please note that the same image directory may contain multiple distro images.

For example, if you build both ``rity-demo-image`` and ``rity-bringup-image`` for g350-EVK:

.. prompt:: bash $

	DISTRO=rity-demo MACHINE=g350-evk bitbake rity-demo-image
	DISTRO=rity-bringup MACHINE=g350-evk bitbake rity-bringup-image

The image directory ``$BUILD_DIR/tmp/deploy/images/g350-evk`` contains both images. 
You can use ``genio-flash-tool -i <image-name>`` to select the image you want to flash.
For example, to flash ``rity-bring-image``, use:

.. prompt:: bash $

	genio-flash -i rity-bringup-image

For more details, please refer to :doc:`/tools/genio-tools` page.


BSP Source Code Modification
============================

Kernel
------

Please note that modifying source code directly under the `build/tmp/work` directory causes a lot of problems.
To modify the source code of kernel, please refer to :doc:`/sw/yocto/kernel-dev` and use ``devtool`` to modify package source code.

Trusted-Firmware-A (BL2/BL31)
-----------------------------

For BL2/BL31 source modification, the BL2/BL31 is implemented and based on Trusted-firmware-A (`TF-A`). If you would like to modify the source code of TF-A, please use ``devtool`` tool and modify the source under `build/workspace` folder.

1. Run ``devtool modify trusted-firmware-a``. This will fetch the sources for the recipe and unpack them to a `workspace/sources/trusted-firmware-a/` directory and initialize it as a git repository if it isn't already one.

.. code-block:: bash

    $ devtool modify trusted-firmware-a

2. Make the changes you want to make to the source.

3. Run a build to test your changes - you can partial build ``trusted-firmware-a``.

.. code-block:: bash

    $ bitbake trusted-firmware-a


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

For BL33 source modification, the BL33 is implemented and based on U-Boot. If you would like to modify the source code of U-Boot, please use ``devtool`` tool and modify the source under `build/workspace` folder.

1. Run ``devtool modify u-boot``. This will fetch the sources for the recipe and unpack them to a `workspace/sources/u-boot/` directory and initialize it as a git repository if it isn't already one.

.. code-block:: bash

    $ devtool modify u-boot

2. Make the changes you want to make to the source.

3. Run a build to test your changes - you can partial build U-Boot.

.. code-block:: bash

    $ bitbake u-boot


Clean Output and Intermediate Files
===================================

The Bitbake system used by Yocto project manages various caches and intermediate files when building recipes.

In some cases, you might want to remove the intermediate files and rebuild images or packages from scratch.
To remove the output of a package recipe, use the command:

.. code-block:: bash

    $ bitbake -c clean <recipe-name>

For example, to remove kernel output and intermediate files, 

.. code-block:: bash

    $ bitbake -c clean virtual/kernel

If you suspect there are corrupted recipe task states, you can clean the ``sstate`` cache by:

.. code-block:: bash

    $ bitbake -c cleansstate virtual/kernel

To learn more about various clean tasks, refer to `Yocto manual <https://docs.yoctoproject.org/3.1.15/ref-manual/ref-tasks.html?highlight=cleansstate#do-clean>`_.