How to develop an X-Linux Expansion Package

Applicable for

STM32MP13x lines, STM32MP15x lines

---

This article explains how to create your own STM32 MPU Expansion Package to extend the limits of the ecosystem.

1 Design of an STM32 MPU Expansion Package for an OpenSTLinux Distribution Package

An STM32 MPU Expansion Package for an OpenSTLinux Yocto distribution is a solution proposed to extend a Distribution Package by providing new features, examples, or demonstrations.

Three possible types of profiles are defined to cover different user needs according to the changes required in the OpenSTLinux distribution:

1. OpenSTLinux tools add-on: use when making changes only at the Linux^® user space level, without applying any change to the boot chain or the Linux^® OS.
2. OpenSTLinux embedded software add-ons: use when modifying the Linux^® kernel part (configuration, device tree update), or/and adding user space applications/frameworks needed to demonstrate the Arm^® Cortex^®-A processor functionality.
3. Coprocessor and OpenSTLinux embedded software add-ons: use in the case of the profile type 2, and/or when modifying the STM32Cube MPU part and/or including new firmware source code example to demonstrate the Cortex^®-M coprocessor functionality.

2 Check for OpenSTLinux compatibility version

To ensure the adherence to a given OpenSTLinux version, the dependency is managed with a dedicated ST_OSTL_COMPATIBILITY_VERSION_<layer_name> variable to set in the I-PACK Yocto meta layer (layer.conf file).
This information is verified at the compilation phase.

<layer_name> is the name define by the BBFILE_COLLECTIONS string value, also present in expansion package layer.conf file.

To get the version to set, refer to the variable value given in meta-st-openstlinux/conf/layer.conf , for example:

ST_OSTL_COMPATIBILITY_VERSION_st-openstlinux = "4.1"

As an illustration, the variable has to be defined as below for a layer name "my_new_layer":

ST_OSTL_COMPATIBILITY_VERSION_my_new_layer = "4.1"

Warning

As soon as a new OpenSTlinux release version or major revision is published, if you want to indicate that the I-Pack is compliant (it means "validated with") with it, you must update the corresponding compatibility version variable ST_OSTL_COMPATIBILITY_VERSION accordingly in the I-Pack Expansion Package; otherwise, a build error is generated.

3 STM32 MPU Expansion cases

3.1 OpenSTLinux tools add-on

This profile type covers the case when only changes or additions are done at the Linux^® user space level for applications, tools, or scripts on the root file system.

Two possible approaches:

• Add a standard Yocto layer to the OpenSTLinux distribution: refer to the existing skeleton example in Yocto Project^®.
• Deploy a Debian package on the target: when all dependencies are already managed in the embedded software on the target, it is possible to install the new applications by using a standard Debian package.

3.2 OpenSTLinux embedded software add-ons

This profile type covers the previous one. It is recommended when some additional changes are required at the Linux^® kernel level (configuration and/or device tree update), and/or when adding user space applications/frameworks needed to demonstrate Cortex^®-A processor functionalities.

For this case, the OpenSTLinux distribution must be updated. The proposed solution is to add a new add-on meta layer to provide the services described below. A meta layer template is proposed as a reference to help modifying the BSP components: meta-st-stm32mp-addons.

Otherwise, if only the user space applications and image must be updated, refer to the existing skeleton example in Yocto Project^® for a standard Yocto layer.

3.2.1 New image creation with additional Linux^® user space packages

Refer to the How_to_create_your_own_image wiki page.

As an example, have a look to the X-LINUX-AI Expansion Package image recipe: https://github.com/STMicroelectronics/meta-st-stm32mpu-ai/blob/master/recipes-st/images/st-image-ai.bb

3.2.2 TF-A, OP-TEE, U-Boot, Kernel device tree(s) update

Two approaches are possible, depending on the way the top device tree source file is written for the given reference board:

• The device tree source file (.dts) contains the complete device tree settings. It is generated with STM32CubeMX (see STM32CubeMX_generated_device_tree)
• A new .dts file inherits from an existing device tree file of an ST board. It is used to modify or add a device tree node and overload the device tree (minor changes compared to existing boards)

For both approaches, the way to declare it in the I-Pack meta layer is the same. It is done in the machine file (conf/machine directory). For example, see conf/machine/stm32mp13-mx.conf (STM32MP13x lines ) or conf/machine/stm32mp15-mx.conf (STM32MP15x lines ).

• Force the new device tree source file usage: ENABLE_CUBEMX_DTB ?= "1"
• Define the .dtb binary name to be generated, which is the same as the .dts file you want to use: CUBEMX_DTB = "<your_dtb_file_name>"
• Define the path for the device tree files: CUBEMX_PROJECT = "'<your_dt_file_path>"

Ensure that the corresponding device tree source files that must be taken into account are present in the path given by the variable CUBEMX_PROJECT previously defined.

Then, as in the examples provided in meta-st-stm32mp-addons, it is possible for each BSP component to define the device tree source file to be used through an update of the corresponding recipes.

Component	Yocto recipe append example for BSP components
TF-A	tf-a-stm32mp_%.bbappend
OP-TEE	optee-os-stm32mp_%.bbappend
U-Boot	u-boot-stm32mp_%.bbappend
Linux Kernel	linux-stm32mp_%.bbappend

3.2.3 Linux^® kernel configuration change

Two possible approaches:

• Make defconfig changes by using a configuration fragment file (recommended)
• Provide a full defconfig file

3.2.3.1 Change defconfig with a configuration fragment file

A simple way to update the Linux^® kernel configuration is to use a fragment file. You can refer to the Yocto Project^® web article Creating Configuration Fragments for information.

The config fragment file must be added in the path meta-st-stm32mp-addons/recipes-kernel/linux/linux-stm32mp/<config_fragment_file_name>.

The linux-stm32mp recipe file must be appended to update the build setup. This is done through the file meta-st-stm32mp-addons/recipes-kernel/linux/linux-stm32mp_%.bbappend.

In this file, the new config fragment file must be added to the variable KERNEL_CONFIG_FRAGMENTS, and listed in the SRC_URI variable as given below:

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://<config_fragment_file_name>"
KERNEL_CONFIG_FRAGMENTS += "<config_fragment_file_name>"

3.2.3.2 Use new full defconfig file

It is also possible to provide a full defconfig file for the Linux^® kernel configuration building.
To create a defconfig file, refer to the Yocto Project^® web article Creating a defconfig File.

The file must be present in the path meta-st-stm32mp-addons/recipes-kernel/linux/linux-stm32mp/<defconfig_file_name>.

The linux-stm32mp recipe file must be appended to update the build setup. This is done through the file meta-st-stm32mp-addons/recipes-kernel/linux/linux-stm32mp_%.bbappend.

In this file, the variable KERNEL_DEFCONFIG must be cleaned, the new variable KERNEL_EXTERNAL_DEFCONFIG must be defined, and the path of the <defconfig_file_name> listed in the SRC_URI variable must be as given below:

FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://<defconfig_file_name>"
KERNEL_DEFCONFIG = ""
KERNEL_EXTERNAL_DEFCONFIG = "<defconfig_file_name>"

3.2.4 Addition of source code / binary files for new applications

Refer to the wiki article How_to_add_a_customer_application.

Two other wiki pages are also proposed to help for meta-st-stm32mp-addons usage:

• How_to_create_a_new_open_embedded_layer
• How_to_create_your_own_machine

3.3 Coprocessor and OpenSTLinux embedded software add-ons

Coming soon

This profile type inherits from OpenSTLinux embedded software add-ons. It is recommended when some changes are required at the STM32Cube MPU part, and/or to include new firmware source code examples to demonstrate a Cortex^®-M coprocessor functionality (including hardware resources reallocations).

4 I-Pack Expansion Package example

X-LINUX-AI_OpenSTLinux_Expansion_Package