.. |br| raw:: html
Building Images =============== .. _mainline-setup-build-directory: Setup Build Directory --------------------- We provide a script, ``karo-setup-release.sh``, that simplifies the setup for our machines. To use the script, the name of the specific machine to be built for needs to be specified as well as the desired distro. The script sets up a directory and the configuration files for the specified machine and distro. It also adds our layers to the ``bblayers.conf`` file. There are different configurations you can choose from. * ``DISTRO`` configurations: .. list-table:: :header-rows: 1 * - ``DISTRO=`` - Description * - karo-minimal - Ka-Ro Linux Distro with minimal read-only rootfs * - karo-wayland - Ka-Ro Linux Distro with wayland backend * - karo-xwayland - Ka-Ro Linux Distro with xwayland backend * - karo-x11 - Ka-Ro Linux Distro with X11 support * Possible ``MACHINE`` configurations: **Renesas** .. list-table:: :header-rows: 2 * - **RZ/G2L Processors** * - ``MACHINE=`` * - qsrz-g2l0 * - txrz-g2l0 * - qsrz-g2l1 * - txrz-g2l1 * - txrz-g2l2 **STM** .. list-table:: :header-rows: 2 * - **STM32MP1 Processors** * - ``MACHINE=`` * - qsmp-1351 * - qsmp-1570 * - qsmp-1530 * - qsmp-1510 * - txmp-1570 * - txmp-1571 **NXP** .. note:: i.MX6 machines are no longer supported in *mickledore* release. .. list-table:: :header-rows: 3 * - *i.MX6UL(L)* single core Cortex A7 - *i.MX6S* single core Cortex A9 - *i.MX6DL* dual core Cortex A9 - *i.MX6Q(P)* quad core Cortex A9 * - **TXUL** - **TX6S** - **TX6U** - **TX6Q** * - ``MACHINE=`` - ``MACHINE=`` - ``MACHINE=`` - ``MACHINE=`` * - txul-5010 - tx6s-8034 - tx6u-8030 - tx6q-1030 * - txul-5011 - tx6s-8035 - tx6u-8033 - tx6q-1036 * - txul-8013 - tx6s-8134 - tx6u-8130 - tx6q-1130 * - - tx6s-8135 - tx6u-8133 - tx6q-8037 * - - - - tx6q-8137 Use this command to setup your build directory (specify the distro, machine, and the build directory): * **General Example:** .. prompt:: :prompts: $ DISTRO= MACHINE= source karo-setup-release.sh -b When the script has run, your current directory changes to the ```` you chose before. * **Specific Example (e.g. QSMP-1570):** .. prompt:: :prompts: $ DISTRO=karo-minimal MACHINE=qsmp-1570 source karo-setup-release.sh -b build-qsmp-1570-karo-minimal * **Returning to existing build:** You can return to an already setup build directory by running: .. prompt:: :prompts: $ source setup-environment local.conf ---------- To enable different features for your build you can modify the ``conf/local.conf`` file inside your **build-directory**. Baseboard (optional) ~~~~~~~~~~~~~~~~~~~~ The baseboard variable only affects the bootloader (:ref:`uboot-guide-idx`) and it's environment. Normally there's no need to set it. Linux related baseboard configurations are done with :ref:`uboot-fdt-overlays-short`. .. table:: :widths: 10 30 +---------------------+---------------------------------------+ | Machine | Supported Baseboards | +=====================+=======================================+ | **General** | +---------------------+---------------------------------------+ | **QS** | * qsbase1 | | solder-in | * qsbase2 | | | * qsbase4 (*default for QSRZ-*) | +---------------------+---------------------------------------+ | **TX** | * mb7 | | plug-in | | +---------------------+---------------------------------------+ | **Additional** | +---------------------+---------------------------------------+ | TXRZ-G2L2 | * lvds-mb | | | | +---------------------+---------------------------------------+ | QSMP-1570 | * qsqlyn1 | | QSRZ-G2L0 | | +---------------------+---------------------------------------+ To set the ``KARO_BASEBOARD`` variable, modify your ``conf/local.conf``: .. code-block:: text KARO_BASEBOARD = "baseboard" Machine Features ~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 * - Machine Feature - Description - Default? * - extmod - Disables ``CONFIG_TRIM_UNUSED_KSYMS``, neccessary for building external kernel modules - No * - lcd - LCD support - Automatically selected via $MACHINE if supported * - lvds - LVDS display support - Automatically selected via $MACHINE if supported * - nand - NAND storage support - Automatically selected via $MACHINE if supported * - sata - SATA interface support - Automatically selected via $MACHINE if supported * - dsi83 - SN65DSI83 mipi-lvds bridge support - Automatically selected via $MACHINE if supported To expand the ``MACHINE_FEATURES`` variable to your needs, modify your ``conf/local.conf``: .. code-block:: text MACHINE_FEATURES:append = " item1 item2 ..." Distro Features ~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 * - Machine Feature - Description - Default? * - bluetooth - Bluetooth support - No * - ipv6 - IPV6 support - No * - systemd - Changes init-system to systemd, e.g. neccessary when using Debian - No * - wifi - WiFi support - No To expand the ``DISTRO_FEATURES`` variable to your needs, modify your ``conf/local.conf``: .. code-block:: text DISTRO_FEATURES:append = " item1 item2 ..." .. _mainline-build-the-image: Build the Image --------------- .. note:: The setup-environment provided by the BSP already sets up a **SSTATE CACHE** to speedup the build process. |br| For more about sstate caches see :ref:`yocto-sstate`. Here are (some of) the different images (and packages) that can be build: .. table:: :widths: 20 30 20 20 +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | Image | Description | ``DISTRO=`` (required) | Provided by layer | +==================================+==================================================================+===========================+===================================+ | **Official Ka-Ro BSP images** | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | karo-image-minimal | Image with minimal read-only rootfs | karo-minimal | meta-karo-distro | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | karo-image-weston | Image with basic weston desktop, graphics accelerated | karo-wayland | meta-karo-distro | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | karo-image-qt6 | Image with basic weston desktop and QT5. | karo-wayland | meta-karo-distro | | | To use it wit QT-Creator see :ref:`qt-guide-index` | | | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | karo-image-x11 | Image with X11 support | karo-x11 | meta-karo-distro | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | **Ka-Ro packages images** | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | u-boot-karo | U-Boot flashable binary | N/A (any) | meta-karo | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | linux-karo | Linux Kernel and specified .dtb files only | N/A (any) | meta-karo | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | **General Yocto / OE images** | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ | core-image-minimal | See `here @ OpenEmbedded Layer Index`_ | N/A (any) | Poky | +----------------------------------+------------------------------------------------------------------+---------------------------+-----------------------------------+ `OpenEmbedded Layer Index `_ `OpenEmbedded Layer Index for Recipes `_ .. rubric:: Examples Build the `kernel image` with the following command inside your ````. .. prompt:: :prompts: $ bitbake linux-karo Build the `karo-image-minimal` with the following command inside your ````. .. prompt:: :prompts: $ bitbake karo-image-minimal Getting the SDK ~~~~~~~~~~~~~~~ To build the SDK of a certain image run inside your ````: .. prompt:: :prompts: $ bitbake -c populate_sdk .. tip:: The SDK can e.g. be used for :ref:`vscode-index`. Image Deployment ---------------- After a build is complete, the created image resides in the ``tmp/deploy/images/`` sub-directory. An image is, for the most part, specific to the machine set in the environment setup. Each image build creates different files. The following files are created for Ka-Ro QSMP/TXMP modules when running *karo-image-minimal*: .. table:: :widths: 25 25 25 +----------------------------------+--------------------------------------------+----------------------+ | Filename | Content | Module Type | +==================================+============================================+======================+ | flashlayout_*.tsv | FlashLayout File for STM32CubeProgrammer | any | +----------------------------------+--------------------------------------------+----------------------+ | uImage-- | Kernel uImage | any | +----------------------------------+--------------------------------------------+----------------------+ | modules-.tgz | Kernel modules | any | +----------------------------------+--------------------------------------------+----------------------+ | -.tar.{bz2|gz} | RFS (bzip2/gzip) tar | any | +----------------------------------+--------------------------------------------+----------------------+ | -.ext4 | RFS ext4 filesystem image | eMMC | +----------------------------------+--------------------------------------------+----------------------+ | -.ubi | RFS `UBI (Unsorted Block Images)`_ | NAND | +----------------------------------+--------------------------------------------+----------------------+ | -.ubifs | RFS `UBIFS (UBI File-System)`_ | NAND | +----------------------------------+--------------------------------------------+----------------------+ | \*.dtb | Device Tree Blob | any | +----------------------------------+--------------------------------------------+----------------------+ | \*.dtbo | Device Tree Overlay Blob | any | +----------------------------------+--------------------------------------------+----------------------+ | **/** | **FlashImage standalone folder** | any | +----------------------------------+--------------------------------------------+----------------------+ | **/uuu.auto** | **UUU FlashImage script** | any | +----------------------------------+--------------------------------------------+----------------------+ QSRZ/TXRZ ~~~~~~~~~ .. tip:: To continue with these images use :ref:`rzg2-flashing` or TFTP boot. QSMP/TXMP ~~~~~~~~~ .. tip:: To continue with these images use :ref:`stm32-programmer-setup` or TFTP boot. .. tip:: See what you can do with Yocto built images at :ref:`txmp-bsp`. If you compiled ``karo-image-qt6`` check out :ref:`qt-guide-index`. TX6/TXUL ~~~~~~~~ .. tip:: To continue with these images use :ref:`mfg-tool-setup` or TFTP boot. |br| **UUU is currently not supported for TX6/TXUL!** .. tip:: See what you can do with Yocto built Images at :ref:`tx6-bsp`. If you compiled ``karo-image-qt5`` check out :ref:`qt-guide-index`. .. _`UBI (Unsorted Block Images)`: http://www.linux-mtd.infradead.org/doc/ubi.html .. _`UBIFS (UBI File-System)`: http://www.linux-mtd.infradead.org/doc/ubifs.html .. _`here @ OpenEmbedded Layer Index`: https://layers.openembedded.org/layerindex/recipe/579/