View source for Yocto: Making Changes to Yocto Meta-Layers

This is a simple example that shows how to add a New Machine in Yocto bitbake meta layer.
=Introduction=
In Yocto terminology a '''machine''' is the target device for which the Yocto image is built. The example machine in this article is CompuLab's [[CL-SOM-iMX8 NXP i.MX8M SW Resources | '''CL-SOM-iMX8''']].

= Adding a New Machine =
Adding a new machine to the Yocto Project is a straightforward process.<br>
This section describes how to add machines that are similar to those that the Yocto Project already supports.<br>
For a complete example that shows how to add a new machine, see the 
[https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#creating-a-new-bsp-layer-using-the-yocto-bsp-script “Creating a New BSP Layer Using the yocto-bsp Script”] section in the Yocto Project Board Support Package (BSP) Developer’s Guide.

== Adding the Machine Configuration File ==

To add a new machine, you need to add a new machine configuration file to the layer’s conf/machine directory.<br>
This configuration file provides details about the device you are adding.

The OpenEmbedded build system uses the root name of the machine configuration file to reference the new machine.<br>
For example, given a machine configuration file named ''cl-som-imx8.conf'', the build system recognizes the machine as “cl-som-imx8”.

The most important variables you must set in your machine configuration file or include from a lower-level configuration file are as follows:

# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-TARGET_ARCH TARGET_ARCH] (e.g. “arm64”)
# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-PREFERRED_PROVIDER PREFERRED_PROVIDER]_virtual/kernel
# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-MACHINE_FEATURES MACHINE_FEATURES] (e.g. “pci wifi bluetooth”)
# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-SERIAL_CONSOLES SERIAL_CONSOLES] (e.g. “115200 ttymxc2”)
# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-KERNEL_IMAGETYPE KERNEL_IMAGETYPE] (e.g. “uImage”)
# [https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-IMAGE_FSTYPES IMAGE_FSTYPES] (e.g. “tar.gz sdcard.gz”)

Some of these variables get inherited from the NXP files:
 conf/machine/include/imx-base.inc
 conf/machine/include/arm/arch-arm64.inc

== Adding a Boot Loader for the Machine ==

The OpenEmbedded build system needs to be able to build a boot loader for the machine.<br>
You need to either create a new boot loader recipe for this machine, or extend an existing boot loader recipe.<br>

=== Extending existing recipe ===
* file location: ''[https://github.com/compulab-yokneam/meta-bsp-imx8mq/blob/master/recipes-bsp/u-boot/u-boot-imx_2018.03.bbappend recipes-bsp/u-boot/u-boot-imx_2018.03.bbappend]''
<pre>
FILESEXTRAPATHS_prepend := "${THISDIR}/compulab/imx8mq:"

include compulab/imx8mq.inc

SRC_URI_append += " \
	https://github.com/compulab-yokneam/logos/raw/master/300x153x8bit/compulab.bmp;protocol=https;md5sum=da59211e201bfcecc53483a0a5c025f1;sha256sum=0a447cc174ca16236ac46c290d6c177cd6be9fc1ad96749c1784d0504522fb47 \
"

do_configure_append_cl-som-imx8 () {
	cp -rfv ${WORKDIR}/compulab.bmp ${S}/tools/logos/
}

PACKAGE_ARCH = "${MACHINE_ARCH}"
COMPATIBLE_MACHINE = "(cl-som-imx8)"
</pre>

== Adding a Kernel for the Machine ==

The OpenEmbedded build system needs to be able to build a kernel for the machine.<br>
You need to either create a new kernel recipe for this machine, or extend an existing kernel recipe.<br>

=== Creating new recipe ===
* file location: ''[https://github.com/compulab-yokneam/meta-bsp-imx8mq/blob/master/recipes-kernel/linux/linux-compulab_4.14.98.bb recipes-kernel/linux/linux-compulab_4.14.98.bb]''
<pre>
SUMMARY = "CompuLab Linux Kernel"
DESCRIPTION = "CompuLab Linux Kernel"

require recipes-kernel/linux/linux-imx.inc
require recipes-kernel/linux/linux-imx-src-${PV}.inc

DEPENDS += "lzop-native bc-native"

FILESEXTRAPATHS_prepend := "${THISDIR}/compulab/imx8mq:"
include compulab/imx8mq.inc

do_configure_append () {
    oe_runmake ${MACHINE}_defconfig
}

KERNEL_MODULE_AUTOLOAD += "goodix"
KERNEL_MODULE_AUTOLOAD += "snd_soc_wm8731"

COMPATIBLE_MACHINE = "cl-som-imx8"
</pre>

In order to use this approach the '''conf/local.conf''' file must have this '''PREFERRED_PROVIDER_virtual/kernel''' value:
<pre>
PREFERRED_PROVIDER_virtual/kernel_cl-som-imx8 = "linux-compulab"
</pre>

=== Extending existing recipe ===
* file location: ''[https://github.com/compulab-yokneam/meta-bsp-imx8mq/blob/master/recipes-kernel/linux/linux-imx_4.14.%25.bbappend recipes-kernel/linux/linux-imx_4.14.%.bbappend]''
<pre>
FILESEXTRAPATHS_prepend := "${THISDIR}/compulab/imx8mq:"

include compulab/imx8mq.inc

do_configure_append () {
    oe_runmake ${MACHINE}_defconfig
}

KERNEL_MODULE_AUTOLOAD += "goodix"
KERNEL_MODULE_AUTOLOAD += "snd_soc_wm8731"

COMPATIBLE_MACHINE = "(cl-som-imx8)"
</pre>

= CompuLab Meta Layer Example =

{{Note | See below a example of the meta-layer's directory tree
See [https://github.com/compulab-yokneam/meta-bsp-imx8mq for the meta-bsp-imx8mq] source files in GitHub. 
}}

The layer folder in built of a few files and directories:
* '''conf/layer.con''' - the layer configuration files
* '''conf/machine/cl-som-imx8.conf''' - the machine configuration files
* '''recipes-bsp/u-boot/u-boot-imx_2018.03.bbappend''' - U-Boot recipe extension of the NXP '''meta-fsl-bsp-release/imx/meta-bsp/recipes-bsp/u-boot/u-boot-imx_2018.03.bb'''
* '''recipes-kernel/linux/linux-imx_4.14.%.bbappend''' - Kernel recipe extension of the NXP '''meta-fsl-bsp-release/imx/meta-bsp/recipes-kernel/linux/linux-imx_4.14.98.bb'''
* '''recipes-bsp''' and '''recipes-kernel''', each containing the recipes for the appropriate software part, here specifically for the '''compulab''' '''imx8mq'''.
* for each of the above, we have :
** a directory containing the patch files
** an imx8mq.inc listing the patch files names
** one or more *.bbappend files containing the actions to taken in addition ("appended")

== CompuLab meta-bsp-imx8mq  meta-layer directory tree ==
<pre>
.
├── conf
│   ├── layer.conf
│   └── machine
│       └── cl-som-imx8.conf
├── recipes-bsp
│   └── u-boot
│       ├── compulab
│       │   ├── imx8mq
│       │   │   ├── 0000-cl-som-imx8-Add-board-support.patch
│       │   │   ├── 0001-cl-som-imx8-Remove-unused-firmware.patch
│       │   │   ├── 0002-cl-som-imx8-Add-usb-support.patch
│       │   │   ├── 0003-cl-som-imx8-Update-Android-support.patch
│       │   │   ├── 0004-cl-som-imx8-Fix-usb-support.patch
│       │   │   ├── 0005-cl-som-imx8-Update-memory-init-code.patch
│       │   │   ├── 0006-cl-som-imx8-pmic-Increase-GPU-power-rail-voltage.patch
│       │   │   ├── 0007-cl-som-imx8-pmic-Increase-DRAM-power-rail-voltage.patch
│       │   │   ├── 0008-cl-som-imx8-Add-board-cfg-GPIO-for-RAM-size.patch
│       │   │   ├── 0009-cl-som-imx8-Refactoring-RAM-configuration.patch
│       │   │   ├── 0010-cl-som-imx8-config-RAM_BOARD_CFG-is-the-default.patch
│       │   │   ├── 0011-cl-som-imx8-defconfig-Enable-USB-ethernet.patch
│       │   │   ├── 0012-cl-som-imx8-defconfig-Add-rev-to-LOCAL_VERSION.patch
│       │   │   ├── 0013-cl-som-imx8-defconfig-Add-d1-d2-configs.patch
│       │   │   ├── 0014-cl-som-imx8-defconfig-Enable-OPTEE.patch
│       │   │   ├── 0015-cl-som-imx8-defconfig-Disable-TMU.patch
│       │   │   ├── 0016-CL-SOM-iMX8-Enable-LED.patch
│       │   │   ├── 0017-Enable-eeprom-cmd.patch
│       │   │   └── cl-som-imx8_defconfig
│       │   └── imx8mq.inc
│       └── u-boot-imx_2018.03.bbappend
└── recipes-kernel
    └── linux
        ├── compulab
        │   ├── imx8mq
        │   │   ├── 0000-cl-som-imx8-Add-CompuLab-device-tree-files.patch
        │   │   ├── 0001-cl-som-imx8-config-Add-defconfig.patch
        │   │   ├── 0002-cl-som-imx8-Add-SoM-driver.patch
        │   │   ├── 0003-sn65dsi83-Add-dsi2lvds-bridge.patch
        │   │   ├── 0004-ov5640_mipi_v2-gpio-can-sleep.patch
        │   │   ├── 0005-cl-som-imx8-dtb-Update-Makefile.patch
        │   │   ├── 0006-cl-som-imx8-Simple-Sound-Support.patch
        │   │   ├── 0007-cl-som-imx8-dts-Device-tree-refactoring.patch
        │   │   ├── 0008-cl-som-imx8-defconfig-Update-defconfig.patch
        │   │   ├── 0009-cl-som-imx8-Fix-SD1_RESET.patch
        │   │   ├── 0010-cl-som-imx8-defconfig-FRAMEBUFFER_CONSOLE_ROTATION-y.patch
        │   │   ├── 0011-cl-som-imx8-dts-Add-a-non-edid-dts-file.patch
        │   │   ├── 0012-imx-hdp-Added-user-defined-video-modes.patch
        │   │   ├── 0013-cl-som-imx8-sb-Add-hubpwren-regulator.patch
        │   │   ├── 0014-cl-som-imx8-defconfig-Update-defconfig.patch
        │   │   ├── 0015-cl-som-imx8-defconfig-Enable-wm8731-with-sdma-as-a-m.patch
        │   │   ├── 0016-cl-som-imx8-Remove-unused-dvfs-regulator.patch
        │   │   ├── 0017-cl-som-imx8-rmpms-Removed-the-rpmsg-pingpong-area.patch
        │   │   ├── 0018-cl-som-imx8-dts-m4-Added-sbc-imx8-m4-file.patch
        │   │   ├── 0019-cl-som-imx8-dts-Change-mipi-dcss-clock-settings.patch
        │   │   ├── 0020-cl-som-imx8-defconfig-Update-config.patch
        │   │   ├── 0021-cl-som-imx8-dts-Fix-the-csi-assigned-clock-rate.patch
        │   │   ├── 0022-cl-som-imx8-dts-Changed-sn65dsi83-clock-to-a-support.patch
        │   │   ├── 0023-cl-som-imx8-dts-Fix-the-dcss-assigned-clocks.patch
        │   │   ├── 0024-cl-som-imx8-dts-Increase-lcdif-max-res-to-1920x1200.patch
        │   │   └── defconfig
        │   └── imx8mq.inc
        └── linux-imx_4.14.%.bbappend
</pre>