Difference between revisions of "How to compile the device tree with the Distribution Package"

<noinclude>

{{ReviewsComments|-- [[User:Yves Coppeaux|Yves Coppeaux]] ([[User talk:Yves Coppeaux|talk]]) 16:56, 20 September 2022 (CEST)<br />bad title for this page but right category, it is not only DTS compile but a permanent distribution update, with a new machine definition via a customize meta-layer included DTS and if needed some recipes<br>

The update of DTS can be made with the update of the meta-st-stm32mp-addons, right ? so it is not mandatory to create a new layer.<br>

If we keep the option to create a new layer, I suggest to keep the name my-custo-layer instead of my-demo-layer created here  [[How to create a new open embedded layer]] }}
{{ReviewsComments | [[User:Romuald Jeanne|Romuald Jeanne]] ([[User talk:Romuald Jeanne|talk]]) 15:57, 21 November 2022 (CET) - This section deals with CubeMX DTS generated file that user want to build through our distribution package. It refers to [[How to create a new open embedded layer]] to initiate the needed layer, but then it explains how to configure the machine that will set-up use of CubeMX DTS files as source. We don't want user to directly modify our meta-st-stm32mp-addons layer, this layer is a sample one to help user to create its own layer and machine to compile the CubeMX DTS files.}}

{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x,STM32MP15x
}}</noinclude>

==Introduction==
This article is intended for Yocto experts, or people who have some practical experience of the Yocto environmment.<br><br>

This section describes the steps needed to create and configure a demo layer using DeviceTree files from the STM32CubeMX tool, and to add and configure a machine similar to those already supported by the OpenSTLinux Distribution Package (in particular the machine delivered inside the existing STM32MP BSP layer 'addons').<br>


Reminder: this addon-layer is deployed under the following path in the delivery : '''<path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/'''

==Creating a new open embedded layer for your demo==
You first need to create a new layer. See the latest  [[How to create a new open embedded layer]]<br><br>

After creation, you have under '''<path of OpenSTLinux distribution delivery>/layers/meta-st/''':
<pre>

$ tree meta-my-demo-layer
meta-my-demo-layer
├── conf
│   └── layer.conf
├── recipes-example
│   └── example
│       └── example.bb
├── COPYING.MIT
└── README

3 directories, 4 files</pre>


===Update layer.conf file===
Open the layer.conf file and add the lines below for the licenses,  demo layer path, and dependency with the STM32MP BSP layer 'addons' :

 EULA_FILE_ST_:{{Highlight|stm32mpmydemo}} = "${LAYERDIR}/conf/eula/${MACHINE}"
 EULA_FILE_ST_MD5SUM_:{{Highlight|stm32mpmydemo}} = "8b505090fb679839cefbcc784afe8ce9"

 #Inform bitbake for adding another location to search for licenses
 LICENSE_PATH += "${LAYERDIR}/files/licenses"

 # Set a variable to get the STM32MP MX BSP location
 {{Highlight|STM32MP_MY_DEMO_BASE}} = "${LAYERDIR}"

 # This should only be incremented on significant changes that may
 # cause compatibility issues with other layers
 LAYERVERSION_meta-my-demo-layer = "1"

 LAYERDEPENDS_meta-my-demo-layer = "{{Highlight|stm-st-stm32mp-mx}}"

 # OpenEmbedded compatibility information
 # This should only be incremented on significant changes that will
 # cause compatibility issues with other layers
 LAYERVERSION_meta-my-demo-layer = "1"
 LAYERSERIES_COMPAT_meta-my-demo-layer = "dunfellkirkstone"

{{Info| LAYERSERIES_COMPAT must be aligned with the version of OpenEmbedded used.<br>Please refer to https://wiki.yoctoproject.org/wiki/Releases}}

===Create the machine for your demo===
====Prepare the machine configuration file====
* Copy the machine delivered inside the existing STM32MP BSP layer 'addons' into your demo layer

 $ cp <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/machine/'''stm32mp1X-mx.conf''' <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/machine/'''stm32mp1-demo.conf'''

* Open stm32mp1-demo.conf and update the line below
 #@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python {{Highlight|layers/meta-st/meta-st-stm32mp-addons}}

* Replace STM32MP_MX_BASE by {{Highlight|STM32MP_MY_DEMO_BASE}}

* Add these lines after the series of includes: 

 # Define specific common machine name
 MACHINEOVERRIDES .= ":{{Highlight|stm32mpmydemo}}"

====Configure the machine configuration file for your demo====
{{:How to create your own machine}}

===Associate EULA with the new demo machine===
Copy the eula folder delivered inside the existing STM32MP BSP layer 'addons' into your demo layer 

 $ cp -Rf <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/'''eula'''/ <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/.

Cleanup unexpected symbolic links from eula folder newly populated:

 $ find <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/eula -type l -exec rm -f {} \;

Then create the symbolic link with the machine used for your demo:

 $ cd <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/eula
 $ ln -sf ST_EULA_SLA stm32mp1-demo

===Move DeviceTree files and project coming from STM32CubeMX tool===
The principle is that the user generates devicetree files for the targeted demo from the STM32CubeMX tool.
{{Warning|'''Most of the time, generated devicetree files - mainly user sections - must be reworked by the end user for compilation and functional purposes. Each demo is delivered with an application note that describe changes applied on STM32CubeMX devicetree files'''}}.{{InternalInfo|For a motor control demo the application note is located [https://epm-st.st.com/ProjectServerST/Wildcat%20APPLI%20Introduction%20Package/Working%20Documents/Support%20and%20Application/Demonstrations/MotorControlAN_v1.01.docx here]}}
These files are then moved into the “mx” folder created into your demo layer  : '''<path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/mx/'''

Sub-folders are created and populated with the generated devicetree files:
 mx/${CUBEMX_PROJECT}/kernel
 mx/${CUBEMX_PROJECT}/u-boot
 mx/${CUBEMX_PROJECT}/tf-a
 mx/${CUBEMX_PROJECT}/optee-os

With {{Highlight|CUBEMX_PROJECT}} that is equal to the value defined inside the machine used for the demo.

===Update the README file===
Please update the README file with the information needed for building and executing the demo.

===Clean up useless content===
You can delete the content of the recipes-example folder created by the create-layer command.

After making all of the updates, your demo layer should be similar to:
<pre>

$ tree meta-my-demo-layer
meta-my-demo-layer
├── conf
│   ├── eula
│   │   ├── ST_EULA_SLA
│   │   ├── stm32mp1-demo -> ST_EULA_SLA
│   │   └──  ...
│   ├── machine
│   │   └── stm32mp1-demo.conf
│   └── layer.conf
├── mx
│   └── ${CUBEMX_PROJECT}
│            ├── kernel
│            │   └── stm32mp1XXx-my-demo-mx.dts
│            ├── optee-os
│            │   └── stm32mp1XXx-my-demo-mx.dts
│            ├── tf-a
│            │   ├── stm32mp1X-mx.dtsi
│            │   ├── stm32mp1XXx-my-demo-mx.dts
│            │   └── stm32mp1XXx-my-demo-mx-fw-config.dts
│            └── u-boot
│                ├── stm32mp1XXx-my-demo-mx.dts
│                └── stm32mp1XXx-my-demo-mx-u-boot.dtsi
├── COPYING.MIT
└── README</pre>


==Adding specific recipes and content necessary for your demo==

Examples of further add-on components: 
* Recipes for installing distro-specific configuration files
* Any image recipes specific to user distribution
* A ''psplash append file'' for a branded splash screen
* Any other append files to make custom changes

Some other added components (*bb) are more specific: images, system services, and so on (a non-exhaustive list is shown below):
* Recipes-core for ''psplash screen'', ''systemd services''
* Recipes-samples for example images
...<br>

<noinclude>

[[Category:How to customize software]]
{{PublicationRequestId | 12272| 2019-06-07}}</noinclude>