Version: scarthgap_2-x

Advanced usage

This section describes how to add customizations to the already existing configurations and describe how the configurator works.

How the `.config` is generated

The generation of the .config file, as said, is the artifact resulting from menuconfig tool processing the configuration.

menuconfig is a Yconfig interface that allows users to interactively navigate and modify the configuration tree. Options are displayed based on dependencies and user selections. Conditional options are visually distinct, often grayed out or hidden when unavailable. menuconfig reads the Yconfig files, creating the interactive interface and, finally, creating the .config:

Yconfig files --> menuconfig --> .config

The Yconfig system is a tool used to manage configuration options for complex projects, such as operating systems or embedded systems. It provides a hierarchical and dependency-aware approach to organizing and selecting configuration settings.

The tree-like hierarchy and dependency-awareness bring many advantages:

Configuration options are grouped into categories and subcategories to make navigation logical and intuitive.
Options can depend on the state of other options or specific conditions. Dependent options are hidden or disabled if their requirements are unmet.

Yconfig supports various types of options:

boolean options (y/n) enable or disable features.
string, integer, and hex options provide customization, such as specifying memory sizes or file paths.

It also allows default values and constraints to simplify the configuration and ensure valid setups. Its logical organization simplifies navigation, dependency awareness prevents invalid configurations, and its flexibility supports diverse project requirements. The user-friendly interface makes it accessible even for complex configurations.

Once the configuration is finalized, a .config file is generated by menuconfig. This file captures the state of all configuration options, including enabled features, disabled options, and specific settings.

The root Yconfig file is layers/base/config/Yconfig/Yconfig. A Yconfig can include other Yconfigs with the syntax:

...
source "<path/to/Yconfig>"
...
osource "<path/to/Yconfig>"
...

where:

source returns an error if the targeted Yconfig is not found.
osource returns a warning if the targeted Yconfig is not found but the execution continues.
<path/to/Yconfig> is the relative path to the targeted Yconfig referred to mconf or conf binaries' paths.

This means that it's easy to spread Yconfig files in many layers, automatically including the needed flags when a layer is included.

Configuration flags clusters

The build configurator core function is to create and process the .config file in order to create the required build environment. A .config file consist in a set of flags such as:

...
CONFIG_EXAMPLE=y
CONFIG_EXAMPLE_FEATURE_DISABLED=n
# CONFIG_EXAMPLE_NOT_ENABLED is not set
CONFIG_EXAMPLE_STRING="default"
...

Depending on the name of the flag some actions can be performed. The build configurator defines clusters of flags to associate the action to flag clusters. For a detailed description of the association between flags and actions, read the documentation in the seco-build-configurator at this link. The documentation has a table containing the matches between flags clusters and the actions performed on the build environment and the syntax that the flags need to let the configurator work properly.

Adding new configuration flags to Yconfig

Creating new configuration entries involves modifying the Yconfig tree. For customers, it's highly recommended to keep Yconfigs in Seco's layers as they are. To add new entries only add Yconfigs in the custom layer and include it sourcing it in the layers/base/config/Yconfig/Yconfig.

Add a variable automatically in the `local.conf`

As an example, consider the custom layer layers/meta-seco/meta-seco-xyz that wants to add a new variable in the local.conf. This is the structure of the layer:

$ tree -a layers/meta-seco/meta-seco-xyz
layers/meta-seco/meta-seco-xyz
├── conf
│   ├── bblayers.conf
│   ├── layer.conf
│   └── SRCREV.conf
└── custom_layer

Create the folder layers/meta-seco/meta-seco-xyz/conf/Yconfig and create into it the file Yconfig_xyz:

$ tree -a layers/meta-seco/meta-seco-xyz
layers/meta-seco/meta-seco-xyz
├── conf
│   ├── bblayers.conf
│   ├── layer.conf
│   ├── SRCREV.conf
│   └── Yconfig
│       └── Yconfig_xyz
└── custom_layer

Write into the file the custom configuration entries. Following the syntax in the repository seco-build-configurator at this link, to add a variable to local.conf add the content to Yconfig_xyz:

menu "XYZ custom configurations"

    config FEATURE_XYZ-NEW-AWESOME-FEATURE
        string "Adding new feature example for meta-seco-xyz"
        default "example-feature"
        help
            Enter the name of the custom feature.

endmenu

NOTE: Always leave an empty line at the end of any Yconfig file. This may cause the error:

../meta-seco/meta-seco-xyz/conf/Yconfig/Yconfig_xyz:52: 'endmenu' in different file than 'menu'

../meta-seco/meta-seco-xyz/conf/Yconfig/Yconfig_xyz:11: location of the 'menu'

even if the menu is correctly closed in the file.

Include the new Yconfig_xyz file sourcing it in the root layers/base/Yconfig/Yconfig adding:

...
...
    comment "Custom XYZ configurations"

    source "../meta-seco/meta-seco-xyz/conf/Yconfig/Yconfig_xyz

In this way, running the configurator with:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -m

it's possible to see that a new menu appeared called XYZ custom configurations in the landing page: Menuconfig customized Yconfig landing page

Entering in that menu it's possible to view that the added configuration has the default value set in Yconfig_xyz. Press Enter on it to edit the new entry added selecting the value example-feature-modified: Menuconfig customized feature

Saving the configuration generates the layers/base/.config that holds the new variable set:

$ cat layers/base/.config
...
#
# XYZ custom configurations
#
CONFIG_FEATURE_XYZ-NEW-AWESOME-FEATURE="example-feature-modified"

Finally, creating the build environment and checking the content of local.conf:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -c

***
    INFO: Found custom layer "seco-xyz"!!! Use it.
***

WARNING: no CONFIG_CLOUD_ASTARTE-URL found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-REALM found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-PAIRING-TOKEN found in the configuration.
WARNING: no RAUC found in the configuration.

Welcome to SECO BSP

The Yocto Project has extensive documentation about OE including a
reference manual which can be found at:
    http://yoctoproject.org/documentation

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/


Your build environment has been configured with:

    MACHINE=seco-rk3568-e09
    SDKMACHINE=i686
    DISTRO=clea-os-fb
    EULA=

yoctouser@f48a332eb475:~/workdir/build_e09_xyz$ cat conf/local.conf | grep ^XYZ
XYZ_NEW_AWESOME_FEATURE = "example-feature-modified"

To find out what are the available actions, look at the documentation of seco-build-configurator at this link.

Add a custom machine to Yconfig

Starting-off from the layer created in the section, the custom layer has the structure:

$ tree -a layers/meta-seco/meta-seco-xyz
layers/meta-seco/meta-seco-xyz
├── conf
│   ├── bblayers.conf
│   ├── layer.conf
│   ├── SRCREV.conf
│   └── Yconfig
│       └── Yconfig_xyz
└── custom_layer

The new custom machine must be added creating a dedicated folder containing the machines in layers/meta-seco/meta-seco-xyz/conf/machine. As an example, the machine used for Seco E09 has been copied into the folder and renamed to differentiate it from the original. Here the steps:

yoctouser@f48a332eb475:~/workdir$ mkdir -p layers/meta-seco/meta-seco-xyz/conf/machine
yoctouser@f48a332eb475:~/workdir$ cp layers/meta-seco/meta-seco-rk/conf/machine/seco-rk3568-e09.conf layers/meta-seco/meta-seco-xyz/conf/machine/seco-rk3568-e09-xyz.conf

Finally, create the file layers/meta-seco/meta-seco-xyz/conf/Yconfig/Yconfig_machine with the content:

    config MACH_MACHINE_seco-rk3568-e09-xyz
        bool "Sailor - codename E09 - XYZ"
        select HW_RK
        depends on ARCH_ARCHITECTURE_rk
        help
            SBC 3.5" board based on Rockchip RK3568 SoC

The final custom layer structure is:

$ tree -a layers/meta-seco/meta-seco-xyz
layers/meta-seco/meta-seco-xyz
├── conf
│   ├── bblayers.conf
│   ├── layer.conf
│   ├── machine
│   │   └── seco-rk3568-e09-xyz.conf
│   ├── SRCREV.conf
│   └── Yconfig
│       ├── Yconfig_machine
│       └── Yconfig_xyz
└── custom_layer

Differently from section, where layers/base/Yconfig/Yconfig need to be updated, when adding machines (Yconfig_machine) and/or distros (Yconfig_distro) they are automatically included.

Running:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -m

Selecting with Enter the menu Seco Machines: Menuconfig customized machine It's possible to see that the custom machine Sailor - codename E09 - XYZ appeared in the machines list:

Then creating the build environment and looking the content of the local.conf:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -c

***
    INFO: Found custom layer "seco-xyz"!!! Use it.
***

WARNING: no CONFIG_CLOUD_ASTARTE-URL found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-REALM found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-PAIRING-TOKEN found in the configuration.
WARNING: no RAUC found in the configuration.
WARNING: multiple machine files for seco-rk3568-e09-xyz in Seco layers.

Welcome to SECO BSP

The Yocto Project has extensive documentation about OE including a
reference manual which can be found at:
    http://yoctoproject.org/documentation

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/


Your build environment has been configured with:

    MACHINE=seco-rk3568-e09-xyz
    SDKMACHINE=i686
    DISTRO=clea-os-fb
    EULA=

yoctouser@f48a332eb475:~/workdir/build_e09_xyz$ cat conf/local.conf | grep ^MACHINE
MACHINE ??= "seco-rk3568-e09-xyz"

it's possible to verify that the variable MACHINE is correctly set to the custom one.

Creating a new defconfig

A defconfig is a configuration that can be directly used by the build configurator. The list of pre-configured defconfigs is returned by:

yoctouser@acbeeb0d56d8:~/workdir$ . ./seco-setup.sh -l

Configuration                           Description
--------------------------------------  ------------------------------------------------------------------------------
qemuarm64_clea-os                       QEMU virt ARMv8 for Clea OS Wayland and default settings
qemuarm_clea-os                         QEMU virt ARMv7 for Clea OS Wayland and default settings
qemux86_64_clea-os                      QEMU x86-64 (q35) for Clea OS and default settings
qemux86_clea-os                         QEMU x86 (q35) for Clea OS and default settings
raspberrypi4_64_clea-os                 Raspberry Pi 4 for Clea OS FB and default settings
raspberrypi5_clea-os                    Raspberry Pi 5 for Clea OS FB and default settings
seco_intel_clea-os                      SECO HW based on INTEL chipsets for Clea OS FB and default settings
seco_sbc_c31_clea-os                    SBC RK3399 C31 board for Clea OS Wayland and default settings
seco_sbc_d23_clea-os                    SBC PX30 D23 board for Clea OS Wayland and default settings
seco_sbc_e09_clea-os                    SBC RK3568 E09 for Clea OS Wayland and default settings

The standard defconfigs are stored in layers/base/configs. It is possible to add new defconfigs in custom layers with a simple procedure:

create the desired configuration with menuconfig. This step can be done either:
- starting from an existing configuration running:
```
. ./seco-setup.sh -d <defconfig>
. ./seco-setup.sh -m
```
- from scratch when there is no layers/base/.config with:
```
. ./seco-setup.sh -m
```
This step it's highly recommended: menuconfig helps to create valid configurations considering the dependencies and the requirements. Doing it by hand is prone to errors.

copy the resulting .config in the destination layer, for example layers/meta-seco/meta-seco-xyz/conf/configs/seco_custom_xyz_clea-os_defconfig. The resulting layer, starting from the structure from this section structure is:

$ tree -a layers/meta-seco/meta-seco-xyz
layers/meta-seco/meta-seco-xyz
├── conf
│   ├── bblayers.conf
│   ├── configs
│   │   └── seco_custom_xyz_clea-os_defconfig
│   ├── layer.conf
│   ├── machine
│   │   └── seco-rk3568-e09-xyz.conf
│   ├── SRCREV.conf
│   └── Yconfig
│       ├── Yconfig_machine
│       └── Yconfig_xyz
└── custom_layer

in the new defconfig add a description line at the very beginning of the file.

To verify that the defconfig can be used directly without passing again from the graphical menuconfig, check that it's listed in the table:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -l

***
    INFO: Found custom layer "seco-xyz"!!! Use it.
***

Configuration                           Description
--------------------------------------  ------------------------------------------------------------------------------
qemuarm64_clea-os                       QEMU virt ARMv8 for Clea OS Wayland and default settings
qemuarm_clea-os                         QEMU virt ARMv7 for Clea OS Wayland and default settings
qemux86_64_clea-os                      QEMU x86-64 (q35) for Clea OS and default settings
qemux86_clea-os                         QEMU x86 (q35) for Clea OS and default settings
raspberrypi4_64_clea-os                 Raspberry Pi 4 for Clea OS FB and default settings
raspberrypi5_clea-os                    Raspberry Pi 5 for Clea OS FB and default settings
seco_intel_clea-os                      SECO HW based on INTEL chipsets for Clea OS FB and default settings
seco_sbc_c31_clea-os                    SBC RK3399 C31 board for Clea OS Wayland and default settings
seco_sbc_d23_clea-os                    SBC PX30 D23 board for Clea OS Wayland and default settings
seco_sbc_e09_clea-os                    SBC RK3568 E09 for Clea OS Wayland and default settings
seco_custom_xyz_clea-os                 Custom board for customer XYZ

Finally, create the build environment with:

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -d seco_custom_xyz_clea-os

***
    INFO: Found custom layer "seco-xyz"!!! Use it.
***


***
    USE defconfig configuration file: seco_custom_xyz_clea-os
    Custom board for customer XYZ
***

yoctouser@f48a332eb475:~/workdir$ . ./seco-setup.sh -c

***
    INFO: Found custom layer "seco-xyz"!!! Use it.
***

WARNING: no CONFIG_CLOUD_ASTARTE-URL found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-REALM found in the configuration.
WARNING: no CONFIG_CLOUD_ASTARTE-PAIRING-TOKEN found in the configuration.
WARNING: no RAUC found in the configuration.
WARNING: multiple machine files for seco-rk3568-e09-xyz in Seco layers.

Welcome to SECO BSP

The Yocto Project has extensive documentation about OE including a
reference manual which can be found at:
    http://yoctoproject.org/documentation

For more information about OpenEmbedded see their website:
    http://www.openembedded.org/


Your build environment has been configured with:

    MACHINE=seco-rk3568-e09-xyz
    SDKMACHINE=i686
    DISTRO=clea-os-fb
    EULA=

yoctouser@f48a332eb475:~/workdir/build_e09_xyz$ 

How the configurator populates `conf` files

To correcly understand the next sections it's required to know the syntax the configurator uses to process the configuration file. The following sections describe how the configurato populates the files in the conf folder in the build directory.

`local.conf`

The configurator starts from poky's template local.conf.sample. It copies this file and rename it with local.conf and clean it up removing any comment into it (lines starting with #).

Then, depending on the .config file, the configurator modifies the local.conf with:

adding at the top of the local.conf the string include SRCREV.conf so that the variables SRCREV for specific packages can be overridden from the build directory.
replace the default value of the mandatory variable MACHINE. This is achieved processing the CONFIG flag matching to the cluster associated to the action that replace the value of a variable in the local.conf.

For seco-build-configurator at version v1.0.4, the cluster CONFIG_MACH must be used. This cluster replaces the value of the MACHINE variable in the local.conf and checks into the layers a suitable machine file.

As an example, for the configuration flag CONFIG_MACH_MACHINE_seco-rk3568-e09=y causes the configurator to write in the local.conf the MACHINE ??= "seco-rk3568-e09" and searches into the layers a machine file called seco-rk3568-e09.conf.
replace the default value of the mandatory variable DISTRO. This is achieved processing the CONFIG flag matching to the cluster associated to the action that replace the value of a variable in the local.conf.

For seco-build-configurator at version v1.0.4, the cluster CONFIG_OS-DISTRO must be used. This cluster replaces the value of the MACHINE variable in the local.conf and checks into the layers a suitable machine file.

As an example, for the configuration flag CONFIG_OS-DISTRO_DISTRO_clea-os-fb=y causes the configurator to write in the local.conf the DISTRO ?= "clea-os-fb".
add to the local.conf any variable in the processed CONFIGs belonging to a cluster that are associated to a this task.

For seco-build-configurator at version v1.0.4, the action that adds variable to the local.conf is called add_to_local_conf. Any cluster associated to this actions adds the variables to the file.

As an example, for the configuration flag CONFIG_FEATURE_XYZ-NEW-AWESOME-FEATURE="example-feature-modified" causes the configurator to write in the local.conf the XYZ_NEW_AWESOME_FEATURE = "example-feature-modified".

`bblayers.conf`

The composition of the bblayers.conf starts from the template in layers/base/config/bblayers.conf. Then depending on the value of:

CONFIG_FLAVOUR_CLEAOS_<flavour>=y the content of the bblayers.conf file in meta-seco/meta-seco-<flavour> is copy-pasted in the finale bblayers.conf.
CONFIG_ARCH_ARCHITECTURE_<arch>=y the content of the bblayers.conf file in meta-seco/meta-seco-<arch> is copy-pasted in the finale bblayers.conf.

These configuration flags are mandatory to succesfully create a valide build environment.

It is also possible to add further content to the file whenever a cluster is associated to an action that adds layers to bblayers.conf.

For seco-build-configurator at version v1.0.4, the action that adds variable to the bblayers.conf is called add_to_bblayers_conf. Any cluster associated to this actions adds the variables to the file. As example, for the configuration flag CONFIG_LAYERS_ADD_META-LAYER="meta-my-layer" causes the configurator to write in the bblayers.conf:

BBLAYERS += " \
    ${BSPDIR}/layers/meta-my-layer \
"

Similarly, it's possible to remove layers with CONFIG_LAYERS_REMOVE_META-LAYER="meta-my-layer". Whenever the bblayers.conf is modified a clean-up is performed to avoid duplicate layers added or empty BBLAYERS blocks.

`SRCREV.conf`

The SRCREV.conf built starting from the final bblayers.conf as last step before completing the creation of the build environment. Essentially, the configurator parses the bblayers.conf looking into all the included layers inside the meta-seco folder. For any of the layers found the SRCREV.conf into them is searched and if the search is successful the path is included in the final SRCREV.conf. For example, let's say the bblayers.conf is:

...
...
...

# Layers at support of current layer (included itself)
BBLAYERS += " \
    ${BSPDIR}/layers/meta-seco/meta-seco-clea-os \
"
# Layers at support of current layer (included itself)
BBLAYERS += " \
    ${BSPDIR}/layers/meta-seco/meta-seco-rk \
"

The configurator looks into layers/meta-seco/meta-seco-clea-os and layers/meta-seco/meta-seco-rk. Assuming that meta-seco-clea-os doesn't have any SRCREV.conf but meta-seco-rk does, the resulting SRCREV.conf is:

$ cat conf/SRCREV.conf 
require ../layers/meta-seco/meta-seco-rk/conf/SRCREV.conf

If none of the layers has SRCREV.conf a warning is raised. This may happen when creating the environment for non-Seco boards such as RaspberryPi or QEMU.

To override the SRCREV in the layer's SRCREV.conf it's possible to write it after the inclusion. For example, to override the SHA of the package linux-seco for Rockchip:

$ cat conf/SRCREV.conf 
require ../layers/meta-seco/meta-seco-rk/conf/SRCREV.conf

SRCREV:pn-linux-seco:linux-seco-rk = "0123456789abcdef"

If the bblayers.conf includes a custom layer, for the same principle of the override, is added at the very end of the file:

$ cat conf/SRCREV.conf 
require ../layers/meta-seco/meta-seco-rk/conf/SRCREV.conf

# Custom SRCREV.conf
require ../layers/meta-seco/meta-seco-xyz/conf/SRCREV.conf

If a custom layer does not include SRCREV.conf the configurator will raise an error as it's mandatory requested.

How the .config is generated​

Configuration flags clusters​

Adding new configuration flags to Yconfig​

Add a variable automatically in the local.conf​

Add a custom machine to Yconfig​

Creating a new defconfig​

How the configurator populates conf files​

local.conf​

bblayers.conf​

SRCREV.conf​