.. _yocto-guide-index:

.. |br| raw:: html

   <br/>

Yocto Guide
===========

.. rubric:: Choosing the right Guide

The table below will help you to decide which guide to use, depending on the module you want to use. In this guides, the right *BSP* is written down, so you don't have to worry about it.

.. note:: If you're new to Yocto we recommend reading the `respective section below`_ before you continue choosing a guide.

.. table::
   :widths: 10 10 10 10 15

   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
   | Module                | Kernel Version                               | Yocto Version | Usage Guide                        | Supported Build Hosts                                                                                                     |
   +=======================+==============================================+===============+====================================+===========================================================================================================================+
   | * TX6 Series |br|     | Linux 5.7.1 |br|                             | Zeus          | .. toctree::                       | `Zeus Reference Manual <https://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html#detailed-supported-distros>`_    |
   | * TXUL Series |br|    | Mainline [3]_                                |               |    :maxdepth: 1                    |                                                                                                                           |
   | * QSMP Series |br|    |                                              |               |                                    |                                                                                                                           |
   | * TXMP Series |br|    |                                              |               |    mainline-zeus/index.rst         |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
   | * TX8M Series         | linux-imx_5.4 |br|                           | Zeus          | .. toctree::                       | `Zeus Reference Manual <https://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html#detailed-supported-distros>`_    |
   | * QS8M Series         | NXP Kernel [6]_                              |               |    :maxdepth: 1                    |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   |                       |                                              |               |    nxp-zeus/index.rst              |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+


Legacy Yocto
------------

These Yocto are still available but **these are deprecated**\ , please use the above given new ones.

.. table::
   :widths: 10 10 10 10 15

   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
   | Module                | Kernel Version                               | Yocto Release | Guide                              | Supported Build Hosts                                                                                                     |
   +=======================+==============================================+===============+====================================+===========================================================================================================================+
   | * QSMP Series         | linux-st_4.19.49 |br|                        | Thud          | .. toctree::                       | `Thud Reference Manual <https://www.yoctoproject.org/docs/2.6.4/ref-manual/ref-manual.html#detailed-supported-distros>`_  |
   | * TXMP Series         | STM32MP Kernel [4]_                          |               |    :maxdepth: 1                    |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   |                       |                                              |               |    yocto-thud-guide/index.rst      |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
   | * TX6 Series          | linux-imx_4.14.98 |br|                       | Sumo          | .. toctree::                       | `Sumo Reference Manual <https://www.yoctoproject.org/docs/2.5.3/ref-manual/ref-manual.html#detailed-supported-distros>`_  |
   | * TXUL Series         | NXP Kernel [5]_                              |               |    :maxdepth: 1                    |                                                                                                                           |
   | * TX8M Series         |                                              |               |                                    |                                                                                                                           |
   | * QS8M Series         |                                              |               |    yocto-sumo-guide/index.rst      |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
   | * TX6 Series          | linux-karo_4.14.24 |br|                      | Rocko         | .. toctree::                       | `Rocko Reference Manual <https://www.yoctoproject.org/docs/2.4.4/ref-manual/ref-manual.html#detailed-supported-distros>`_ |
   | * TXUL Series         | Mainline LTS [3]_                            |               |    :maxdepth: 1                    |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   |                       |                                              |               |    yocto-rocko-guide/index.rst     |                                                                                                                           |
   |                       |                                              |               |                                    |                                                                                                                           |
   +-----------------------+----------------------------------------------+---------------+------------------------------------+---------------------------------------------------------------------------------------------------------------------------+


If you're new to Yocto
------------------------

This is our Yocto Guide. First, lets explain some terms:

* **BSP** - **B**\ oard **S**\ upport **P**\ ackage:

  *A Board Support Package (BSP) is a collection of information that defines how to support a particular hardware device, set of devices, or hardware platform. The BSP includes information about the hardware features present on the device and kernel configuration information along with any additional hardware drivers required. The BSP also lists any additional software components required in addition to a generic Linux software stack for both essential and optional platform features.* [1]_

* **BSP-Layer**:

  See `section 1.1 <https://www.yoctoproject.org/docs/3.0.2/bsp-guide/bsp-guide.html#bsp-layers>`_ in the official Yocto documentation.

* **Recipe**:

  *Recipes (.bb files) are fundamental components in the Yocto Project environment. Each software component built by the OpenEmbedded build system requires a recipe to define the component.* [2]_

On GitHub we are providing different *BSP's* and layers. The following table should give you an overview.

.. table::
    :widths: 20 15 65

    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | Repository                                                                                     | Type         | Description                                                                                                                   |
    +================================================================================================+==============+===============================================================================================================================+
    | `karo-stm-bsp <https://github.com/karo-electronics/karo-stm-bsp>`_                             | *BSP*        | Ka-Ro's Yocto BSP for our STM-processor boards. This expands the ST BSP.                                                      |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `meta-karo-stm <https://github.com/karo-electronics/meta-karo-stm>`_                           | *Layer*      | Ka-Ro's Yocto Layer for Boards with STM Processors - Mainly expanding the meta-st layer.                                      |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `karo-nxp-bsp <https://github.com/karo-electronics/karo-nxp-bsp>`_                             | *BSP*        | Ka-Ro flavoured NXP i.MX Yocto BSP.                                                                                           |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `meta-karo-nxp <https://github.com/karo-electronics/meta-karo-nxp>`_                           | *Layer*      | Ka-Ro's Yocto layer for NXP i.MX Processors based boards.                                                                     |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `karo-bsp <https://github.com/karo-electronics/karo-bsp>`_                                     | *BSP*        | Ka-Ro's Mainline Yocto BSP for boards.                                                                                        |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `meta-karo <https://github.com/karo-electronics/meta-karo>`_                                   | *Layer*      | Ka-Ro's Mainline Yocto layer for our CoMs.                                                                                    |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+
    | `meta-karo-distro <https://github.com/karo-electronics/meta-karo>`_                            | *Layer*      | Ka-Ro's Mainline Yocto Distro layer.                                                                                          |
    +------------------------------------------------------------------------------------------------+--------------+-------------------------------------------------------------------------------------------------------------------------------+


.. rubric:: Glossary

.. [1] Further information: `https://www.yoctoproject.org/docs/3.0.2/bsp-guide/bsp-guide.html <https://www.yoctoproject.org/docs/3.0.2/bsp-guide/bsp-guide.html>`_
.. [2] From: `https://www.yoctoproject.org/docs/3.0.2/dev-manual/dev-manual.html#new-recipe-writing-a-new-recipe <https://www.yoctoproject.org/docs/3.0.2/dev-manual/dev-manual.html#new-recipe-writing-a-new-recipe>`_
.. [3] From `Kernel.org <https://www.kernel.org/>`_ / `git <https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git>`_
.. [4] As given by STM's Yocto - `STM kernel recipe <https://github.com/STMicroelectronics/meta-st-stm32mp/blob/thud/recipes-kernel/linux/linux-stm32mp_4.19.bb>`_
.. [5] As given by NXP's 4.14 Yocto - `NXP kernel recipe <https://source.codeaurora.org/external/imx/meta-fsl-bsp-release/tree/imx/meta-bsp/recipes-kernel/linux/linux-imx_4.14.98.bb?h=sumo-4.14.98-2.3.0>`_
.. [6] As given by NXP's 5.4 Yocto - `NXP kernel recipe <https://source.codeaurora.org/external/imx/meta-imx/tree/meta-bsp/recipes-kernel/linux/linux-imx_5.4.bb?h=zeus-5.4.24-2.1.0>`_

.. _`respective section below`: `If you're new to Yocto`_