Difference between revisions of "How to create your own machine"

[quality revision] [quality revision]
(Create symbolic link for EULA with new machine created)
(Edit the new machine file: stm32mp1-.conf)

Template:ArticleMainWriter Template:ArticleApprovedVersion

1 Introduction[edit]

For your own needs, you can add in the Yocto project a new machine reflecting your own board and your own features.
This article is reserved to Yocto experts or at least people who have already practiced with the Yocto environmment.

This section describes how to add and configure a machine that is similar to those that the OpenSTLinux Distribution Package already supports.
This customer machine is associated to STM32CubeMX tool which provides DeviceTree files per component (tf-a, u-boot and kernel).

We suppose here that all the material described below is done inside an existing STM32MP BSP layer 'addons'.
For reminder this addons layer is deployed here in our delivery : <path of OpenSTLinux distribution delivery>STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/

2 Generate devicetreedevice tree[edit]

The principle is that the user generates devicetree device tree files from the STM32CubeMX tool.
With the STM32CubeMX tool, the user browses inside the OpenSTLinux distribution Distribution Package file system until “mx” folder located into STM32MP BSP layer addons : <path of OpenSTLinux distribution delivery>STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/mx/

  • 3 sub-folders are created and populated with generated devicetree device tree files :
- <ProjectName>/kernel
- <ProjectName>/u-boot
- <ProjectName>/tf-a

Where <ProjectName> is the “STM32CubeMX STM32CubeMX user project name”

Each directory of <ProjectName> contains devicetree device tree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).
Please refer to this page for more details on this tool and its usage :


3 Create a custom customer machine[edit]

Create a machine based on the one provided by ST and align some environment variables with the content of mx/<ProjectName> sub-folders

3.1 Create the new machine[edit]

  $> cd <path of OpenSTLinux distribution delivery>STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
  $> cp stm32mp1-mx.conf stm32mp1-<ProjectName>.conf

3.2 Edit the new machine file: stm32mp1-<ProjectName>.conf[edit]

In the customer machine file, move to User customizing sections paragraph to configure your machine:

  • Boot Scheme (default configuration is trusted)
To select your boot scheme configuration(s), comment and uncomment the BOOTSCHEME_LABELS lines.
  • Boot Device Choice (default configuration is sdcard)
For ecosystem release v1.2.0 Warning.png
To select your boot device configuration(s), comment and uncomment the BOOTDEVICE_LABELS lines.
For ecosystem release v1.1.0 Warning.png
To select your boot device configuration(s), comment and uncomment the FLASHLAYOUT_CONFIG_LABELS lines.
  • Board Type Choice (default configuration is stm32mp157c-ev1)
For ecosystem release v1.2.0 Warning.png
To select your original device tree configuration, comment and uncomment the 'CUBEMX_BOARD_REFERENCE lines.
For ecosystem release v1.1.0 Warning.png
To select your original device tree configuration, comment and uncomment the CUBEMX_DT_FILE_BASE lines.
  • CubeMX Project config (default configuration is empty)
You have to uncomment and configure the following variables to set your CubeMX project:
- CUBEMX_DTB name of CubeMX generated device tree files, without file extension (e.g. stm32mp157c-<ProjectName>-mx)
- CUBEMX_PROJECT path of CubeMX generated device tree files inside mx folder (e.g. <ProjectName>)

You should get something like following example :

For ecosystem release v1.2.0 Warning.png


#@TYPE: $>Machine
cd include
  $> cp stm32mp1-mx-config.inc stm32mp1-<ProjectName>#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python

include conf/machine/include/st-machine-common-stm32mp.inc
include conf/machine/include/stm32mp1-mx-config.inc
  $> cp include conf/machine/include/stm32mp1-mx-extlinux-config.inc
include conf/machine/include/stm32mp1-<ProjectName>mx-extlinux-config.inc

3.2 Edit the new machine file: stm32mp1-<ProjectName>.conf[edit]

Replace these 2 lines :

common.inc

# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_TFA     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_UBOOT   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_LINUX   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_OPTEEOS = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
#BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the boot device supported
#BOOTDEVICE_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
#BOOTDEVICE_LABELS += "emmc"
#BOOTDEVICE_LABELS += "nand-4-256"
#BOOTDEVICE_LABELS += "nor-emmc"
#BOOTDEVICE_LABELS += "nor-nand-4-256"
#BOOTDEVICE_LABELS += "nor-sdcard"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_BOARD_REFERENCE = "stm32mp157a-dk1"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-dk2"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
#CUBEMX_DTB = "stm32mp157c-my-demo"
#CUBEMX_PROJECT = "STM32MP157C-EV1/my-demo/DeviceTree/my-demo"

For ecosystem release v1.1.0 Warning.png



#@TYPE: Machine
#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python

include conf/machine/include/
stm32mp1
st-
mx
machine-
config
common-stm32mp.inc
include conf/machine/include/stm32mp1-mx-
extlinux-
config.inc

By these ones :

include conf/machine/include/stm32mp1-
<ProjectName>
mx-extlinux-config.inc
include conf/machine/include/stm32mp1-
<ProjectName>
mx-
extlinux-config.inc 3.3 Edit the new machine config file: stm32mp1-<ProjectName>-config.inc[edit]

In this config file you can select :

* boot scheme (by default trusted is set)
* boot device  (by default sdcard is set)
* board (by default eval is set)
* name of CubeMX Board DeviceTree files (by default stm32mp157c-defaultmxconfig-mx is commented)
* path of CubeMX Board DeviceTree files (by default STM32MP157C-EV1/Templates/DefaultMXConfig/DeviceTree/DefaultMXConfig is commented)

To select one of each parameter you have just to comment and uncomment lines, and modify CUBEMX_DTB accordingly to the name of CubeMX Board DeviceTree files

3.4
common.inc

# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_pn-tf-a-stm32mp     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_pn-u-boot-stm32mp   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_pn-linux-stm32mp    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_pn-optee-os-stm32mp = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the config labels to use to generate flashlayout file
FLASHLAYOUT_CONFIG_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
FLASHLAYOUT_CONFIG_LABELS += "emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nand-4-256"
#FLASHLAYOUT_CONFIG_LABELS += "nor-sdcard"
#FLASHLAYOUT_CONFIG_LABELS += "nor-emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nor-nand-4-256"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_DT_FILE_BASE = "stm32mp157a-dk1"
#CUBEMX_DT_FILE_BASE = "stm32mp157c-dk2"
CUBEMX_DT_FILE_BASE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
CUBEMX_DTB = "stm32mp157c-<ProjectName>-mx"
CUBEMX_PROJECT = "<ProjectName>"


3.3 Create symbolic link for EULA with new machine created[edit]

For having the To support of GPU and thirdparty stuffthird party content, you need to accept the EULA and the EULA must have a specific name : name of new machine . So a symbolic link must be created with the EULA existing file and the new machine :

  $> cd <path of OpenSTLinux distribution delivery>STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
  $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>

4 Miscellaneous[edit]

4.1 MACHINEOVERRIDES regular expression[edit]

In each customer machine we retrieve this line:

MACHINEOVERRIDES .= ":stm32mpcommonmx"

A regular expression that resolves to one or more target machines with which a recipe is compatible.

The impact in the build environment is that recipes can now do things conditionally only on the builds for all mx specific machines: stm32mpcommonmx
It is very useful in some existing recipes to keep the compatibility for all stm32mp1-<ProjectName>.conf machines.
For instance use it like this (as it is done in the recipe <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/recipes-bsp/alsa/alsa-state-stm32mp1.bbappend):
SRC_URI_append_stm32mpcommonmx

The append will be applied for all machines (all stm32mp1-<ProjectName>.conf) which include MACHINEOVERRIDES .= ":stm32mpcommonmx"

So it avoids to create an append file by customer machine.

4.2 STM32CubeMX class[edit]

A dedicated class is provided here :

<STM32MP BSP layer addons>/classes/cubemx-stm32mp.bbclass

The main goal of this class is to manage any change done by the customer in sub folders mx/<ProjectName>/...

So if a devicetree device tree file is updated for one or more of components, this change will be taken into account automatically during the next compilation done in the Distribution Package.

5 Compile your image with the yocto build process[edit]

 $> cd <path of yocto delivery>
 (directory which contains meta-st, openembedded-core, meta-openembedded)
$> MACHINE=stm32mp1-<ProjectName> DISTRO=openstlinux-weston source layers/meta-st/script/envsetup.sh Accept the term of EULA (if you agree with)
$> bitbake st-image-weston The generated images are available on build-openstlinuxweston-stm32mp1-<ProjectName>/tmp-glibc/deploy/images/stm32mp1-<ProjectName>
Warning.png In case build fail for an error in the machine.conf, pay attention to do a -c cleanall prior to relaunch the build after correction


<noinclude>

{{ArticleMainWriter | ChristopheM}}
{{ArticleApprovedVersion | ChristopheM | BernardP, ChristopheP,Jean-ChristopheT, DenisH, GeraldB | No previous approved version | AlainF - 09Jan'19 - 10212 | 09Jan'19}} 
[[Category:Distribution Package]]</noinclude>

==Introduction==
For your own needs, you can add in the Yocto project a new machine reflecting your own board and your own features.<br>

This article is reserved to Yocto experts or at least people who have already practiced with the Yocto environmment.<br><br>

This section describes how to add and configure a machine that is similar to those that the OpenSTLinux Distribution Package already supports.<br>

This customer machine is associated to STM32CubeMX tool which provides DeviceTree files per component (tf-a, u-boot and kernel).<br><br>


We suppose here that all the material described below is done inside an existing STM32MP BSP layer 'addons'.<br>

For reminder this addons layer is deployed here in our delivery : '''<path of OpenSTLinux distribution deliverySTM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/'''

==Generate devicetreedevice tree==
The principle is that the user generates devicetree device tree files from the [[STM32CubeMX | STM32CubeMX tool]].<br>

With the STM32CubeMX tool, the user browses inside the OpenSTLinux distribution Distribution Package file system until “mx” folder located into STM32MP BSP layer addons :
'''<path of OpenSTLinux distribution deliverySTM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/mx/'''

*3 sub-folders are created and populated with generated devicetree device tree files :**:- <ProjectName>/kernel**:- <ProjectName>/u-boot**:- <ProjectName>/tf-a
Where <ProjectName> is the “STM32CubeMX“[[STM32CubeMX]] user project name”

Each directory of <ProjectName> contains devicetree device tree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).<br>
Please refer to this page for more details on this tool and its usage :
*[[STM32CubeMX]]
{{InternalInfo|Have a look also on this [https://epm-st.st.com/ProjectServerST/Wildcat%20MPU%20(500)/Working%20Documents/Tools/Tools/CubeMX/DT%20Generation/CMX_DT_Generation_RequirementsAndSpecifications.docx STM32CubeMX Requirements And Specifications] document for more details}}

==Create a customcustomer machine==
Create a machine based on the one provided by ST and align some environment variables with the content of mx/<ProjectName> sub-folders
===Create the new machine===
   $> cd <path of OpenSTLinux distribution deliverySTM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
   $> cp stm32mp1-mx.conf stm32mp1-<ProjectName>.conf
  $> cd include
   $> cp stm32mp1-mx-config.inc stm32mp1-<ProjectName>-config.inc
   $> cp stm32mp1-mx-extlinux-config.inc stm32mp1-<ProjectName>-extlinux-config.inc

===Edit the new machine file: stm32mp1-<ProjectName>.conf===
Replace these 2 lines :===Edit the new machine file: stm32mp1-<ProjectName>.conf===
In the customer machine file, move to ''User customizing sections'' paragraph to configure your machine:
* '''Boot Scheme''' (default configuration is ''trusted'')
: To select your boot scheme configuration(s), comment and uncomment the ''BOOTSCHEME_LABELS'' lines.
* '''Boot Device Choice''' (default configuration is ''sdcard'')
: For {{EcosystemRelease | revision=1.2.0 | range=and after}}
: To select your boot device configuration(s), comment and uncomment the ''BOOTDEVICE_LABELS'' lines.
: For {{EcosystemRelease | revision=1.1.0 | range=and before}}
: To select your boot device configuration(s), comment and uncomment the ''FLASHLAYOUT_CONFIG_LABELS'' lines.
* '''Board Type Choice''' (default configuration is ''stm32mp157c-ev1'')
: For {{EcosystemRelease | revision=1.2.0 | range=and after}}
: To select your original device tree configuration, comment and uncomment the 'CUBEMX_BOARD_REFERENCE'' lines.
: For {{EcosystemRelease | revision=1.1.0 | range=and before}}
: To select your original device tree configuration, comment and uncomment the ''CUBEMX_DT_FILE_BASE'' lines.
* '''CubeMX Project config''' (default configuration is empty)
: You have to uncomment and configure the following variables to set your CubeMX project:
:- ''CUBEMX_DTB'' name of CubeMX generated device tree files, without file extension (e.g. stm32mp157c-<ProjectName>-mx)
:- ''CUBEMX_PROJECT'' path of CubeMX generated device tree files inside ''mx'' folder (e.g. <ProjectName>)

You should get something like following example : 

For {{EcosystemRelease | revision=1.2.0 | range=and after}}<pre>

#@TYPE: Machine
#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python
include conf/machine/include/stm32mp1-mx-config.incst-machine-common-stm32mp.incinclude conf/machine/include/stm32mp1-mx-extlinux-config.incBy these ones :include conf/machine/include/stm32mp1-<ProjectName>-mx-extlinux-config.inc include conf/machine/include/stm32mp1-<ProjectName>-extlinux-configmx-common.inc
===Edit the new machine config file: stm32mp1-<ProjectName>-config.inc===
In this config file you can select :
 * boot scheme (by default trusted is set)
 * boot device  (by default sdcard is set)
 * board (by default eval is set)
 * name of CubeMX Board DeviceTree files (by default stm32mp157c-defaultmxconfig-mx is commented)
 * path of CubeMX Board DeviceTree files (by default STM32MP157C-EV1/Templates/DefaultMXConfig/DeviceTree/DefaultMXConfig is commented)

To select one of each parameter you have just to comment and uncomment lines, and modify CUBEMX_DTB accordingly to the name of CubeMX Board DeviceTree files

===Create symbolic link for EULA with new machine created===

{{ReviewsComments|DHU W10.2: To support GPU and third party content, you need to accept the EULA.}}
{{ReviewsComments|DHU W10.2: "The EULA must have a specific name..." Unclear, I understand that a new EULA must be created using a link, but this is not crystal clear}}

For having the support of GPU and thirdparty stuff, you need to accept the EULA and the EULA must have a specific name : name of new machine
   $> cd <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
   $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>


==Miscellaneous==
===MACHINEOVERRIDES regular expression===
In each customer machine we retrieve this line:
 MACHINEOVERRIDES .= ":stm32mpcommonmx"

A regular expression that resolves to one or more target machines with which a recipe is compatible.<br>


The impact in the build environment is that recipes can now do things conditionally only on the builds for all mx specific machines: stm32mpcommonmx<br>

It is very useful in some existing recipes to keep the compatibility for all stm32mp1-<ProjectName>.conf machines.<br>

For instance use it like this (as it is done in the recipe <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/recipes-bsp/alsa/alsa-state-stm32mp1.bbappend):
 SRC_URI_append_stm32mpcommonmx
The append will be applied for all machines ''(all stm32mp1-<ProjectName>.conf)'' which include '''MACHINEOVERRIDES .= ":stm32mpcommonmx"'''

So it avoids to create an append file by customer machine.

===# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_TFA     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_UBOOT   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_LINUX   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_OPTEEOS = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
#BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the boot device supported
#BOOTDEVICE_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
#BOOTDEVICE_LABELS += "emmc"
#BOOTDEVICE_LABELS += "nand-4-256"
#BOOTDEVICE_LABELS += "nor-emmc"
#BOOTDEVICE_LABELS += "nor-nand-4-256"
#BOOTDEVICE_LABELS += "nor-sdcard"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_BOARD_REFERENCE = "stm32mp157a-dk1"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-dk2"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
#CUBEMX_DTB = "stm32mp157c-my-demo"
#CUBEMX_PROJECT = "STM32MP157C-EV1/my-demo/DeviceTree/my-demo"</pre>

<div class="mw-collapsible mw-collapsed">

For {{EcosystemRelease | revision=1.1.0 | range=and before}}<div class="mw-collapsible-content">
<pre>


#@TYPE: Machine
#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python

include conf/machine/include/st-machine-common-stm32mp.inc
include conf/machine/include/stm32mp1-mx-config.inc
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
include conf/machine/include/stm32mp1-mx-common.inc

# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_pn-tf-a-stm32mp     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_pn-u-boot-stm32mp   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_pn-linux-stm32mp    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_pn-optee-os-stm32mp = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the config labels to use to generate flashlayout file
FLASHLAYOUT_CONFIG_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
FLASHLAYOUT_CONFIG_LABELS += "emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nand-4-256"
#FLASHLAYOUT_CONFIG_LABELS += "nor-sdcard"
#FLASHLAYOUT_CONFIG_LABELS += "nor-emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nor-nand-4-256"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_DT_FILE_BASE = "stm32mp157a-dk1"
#CUBEMX_DT_FILE_BASE = "stm32mp157c-dk2"
CUBEMX_DT_FILE_BASE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
CUBEMX_DTB = "stm32mp157c-<ProjectName>-mx"
CUBEMX_PROJECT = "<ProjectName>"
</pre>
</div></div>


===Create symbolic link for EULA with new machine created===
To support GPU and third party content, you need to accept the EULA. 
So a symbolic link must be created with the EULA existing file and  the new machine :
   $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
   $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>


==Miscellaneous==
===STM32CubeMX class===
A dedicated class is provided here :  <STM32MP BSP layer addons>/classes/cubemx-stm32mp.bbclass
The main goal of this class is to manage any change done by the customer in sub folders mx/<ProjectName>/...

So if a devicetree device tree file is updated for one or more of components, this change will be taken into account automatically during the next compilation done in the Distribution Package.

==Compile your image with the yocto build process==
  $> cd <path of yocto delivery>

  (directory which contains meta-st, openembedded-core, meta-openembedded)<br>

  $> MACHINE=stm32mp1-<ProjectName> DISTRO=openstlinux-weston source layers/meta-st/script/envsetup.sh
 Accept the term of EULA (if you agree with)<br>

  $> bitbake st-image-weston
 The generated images are available on build-openstlinuxweston-stm32mp1-<ProjectName>/tmp-glibc/deploy/images/stm32mp1-<ProjectName>


{{Warning | In case build fail for an error in the machine.conf, pay attention to do a -c cleanall prior to relaunch the build after correction }}
<noinclude>

[[Category:Distribution Package]]
{{PublicationRequestId | 10212 (AlainF) | 2019-01-09}}</noinclude>
(29 intermediate revisions by 8 users not shown)
Line 1: Line 1:
<noinclude>
 
{{ArticleMainWriter | ChristopheM}}
 
{{ArticleApprovedVersion | ChristopheM | BernardP, ChristopheP,Jean-ChristopheT, DenisH, GeraldB | No previous approved version | AlainF - 09Jan'19 - 10212 | 09Jan'19}}
 
[[Category:Distribution Package]]
 
</noinclude>
 
 
 
==Introduction==
 
==Introduction==
 
For your own needs, you can add in the Yocto project a new machine reflecting your own board and your own features.<br>
 
For your own needs, you can add in the Yocto project a new machine reflecting your own board and your own features.<br>
Line 12: Line 6:
   
 
We suppose here that all the material described below is done inside an existing STM32MP BSP layer 'addons'.<br>
 
We suppose here that all the material described below is done inside an existing STM32MP BSP layer 'addons'.<br>
For reminder this addons layer is deployed here in our delivery : '''<path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/'''
+
For reminder this addons layer is deployed here in our delivery : '''<path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/'''
  +
 
  +
==Generate device tree==
  +
The principle is that the user generates device tree files from the [[STM32CubeMX | STM32CubeMX tool]].<br>
  +
With the STM32CubeMX tool, the user browses inside the OpenSTLinux Distribution Package file system until “mx” folder located into STM32MP BSP layer addons :
  +
'''<path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/mx/'''
   
==Generate devicetree==
+
*3 sub-folders are created and populated with generated device tree files :
The principle is that the user generates devicetree files from the STM32CubeMX tool.<br>
+
:- <ProjectName>/kernel
With the STM32CubeMX tool, the user browses inside the OpenSTLinux distribution file system until “mx” folder located into STM32MP BSP layer addons :
+
:- <ProjectName>/u-boot
'''<path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/mx/'''
+
:- <ProjectName>/tf-a
  +
Where <ProjectName> is the “[[STM32CubeMX]] user project name”
   
*3 sub-folders are created and populated with generated devicetree files :
+
Each directory of <ProjectName> contains device tree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).<br>
**<ProjectName>/kernel
 
**<ProjectName>/u-boot
 
**<ProjectName>/tf-a
 
Where <ProjectName> is the “STM32CubeMX user project name”
 
   
Each directory of <ProjectName> contains devicetree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).<br>
 
Please refer to this page for more details on this tool and its usage :
 
*[[STM32CubeMX]]
 
 
{{InternalInfo|Have a look also on this [https://epm-st.st.com/ProjectServerST/Wildcat%20MPU%20(500)/Working%20Documents/Tools/Tools/CubeMX/DT%20Generation/CMX_DT_Generation_RequirementsAndSpecifications.docx STM32CubeMX Requirements And Specifications] document for more details}}
 
{{InternalInfo|Have a look also on this [https://epm-st.st.com/ProjectServerST/Wildcat%20MPU%20(500)/Working%20Documents/Tools/Tools/CubeMX/DT%20Generation/CMX_DT_Generation_RequirementsAndSpecifications.docx STM32CubeMX Requirements And Specifications] document for more details}}
   
==Create a custom machine==
+
==Create a customer machine==
 
Create a machine based on the one provided by ST and align some environment variables with the content of mx/<ProjectName> sub-folders
 
Create a machine based on the one provided by ST and align some environment variables with the content of mx/<ProjectName> sub-folders
 
===Create the new machine===
 
===Create the new machine===
   $> cd <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
+
   $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
 
   $> cp stm32mp1-mx.conf stm32mp1-<ProjectName>.conf
 
   $> cp stm32mp1-mx.conf stm32mp1-<ProjectName>.conf
  $> cd include
 
  $> cp stm32mp1-mx-config.inc stm32mp1-<ProjectName>-config.inc
 
  $> cp stm32mp1-mx-extlinux-config.inc stm32mp1-<ProjectName>-extlinux-config.inc
 
   
 
===Edit the new machine file: stm32mp1-<ProjectName>.conf===
 
===Edit the new machine file: stm32mp1-<ProjectName>.conf===
Replace these 2 lines :
+
In the customer machine file, move to ''User customizing sections'' paragraph to configure your machine:
include conf/machine/include/stm32mp1-mx-config.inc
+
* '''Boot Scheme''' (default configuration is ''trusted'')
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
+
: To select your boot scheme configuration(s), comment and uncomment the ''BOOTSCHEME_LABELS'' lines.
By these ones :
+
* '''Boot Device Choice''' (default configuration is ''sdcard'')
include conf/machine/include/stm32mp1-<ProjectName>-config.inc
+
: For {{EcosystemRelease | revision=1.2.0 | range=and after}}
include conf/machine/include/stm32mp1-<ProjectName>-extlinux-config.inc
+
: To select your boot device configuration(s), comment and uncomment the ''BOOTDEVICE_LABELS'' lines.
  +
: For {{EcosystemRelease | revision=1.1.0 | range=and before}}
  +
: To select your boot device configuration(s), comment and uncomment the ''FLASHLAYOUT_CONFIG_LABELS'' lines.
  +
* '''Board Type Choice''' (default configuration is ''stm32mp157c-ev1'')
  +
: For {{EcosystemRelease | revision=1.2.0 | range=and after}}
  +
: To select your original device tree configuration, comment and uncomment the 'CUBEMX_BOARD_REFERENCE'' lines.
  +
: For {{EcosystemRelease | revision=1.1.0 | range=and before}}
  +
: To select your original device tree configuration, comment and uncomment the ''CUBEMX_DT_FILE_BASE'' lines.
  +
* '''CubeMX Project config''' (default configuration is empty)
  +
: You have to uncomment and configure the following variables to set your CubeMX project:
  +
:- ''CUBEMX_DTB'' name of CubeMX generated device tree files, without file extension (e.g. stm32mp157c-<ProjectName>-mx)
  +
:- ''CUBEMX_PROJECT'' path of CubeMX generated device tree files inside ''mx'' folder (e.g. <ProjectName>)
  +
 
  +
You should get something like following example :  
  +
 
  +
For {{EcosystemRelease | revision=1.2.0 | range=and after}}
  +
<pre>
  +
#@TYPE: Machine
  +
#@NAME: stm32mp1-mx
  +
#@DESCRIPTION: Configuration for STM32CubeMX generated project
  +
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python
   
===Edit the new machine config file: stm32mp1-<ProjectName>-config.inc===
+
include conf/machine/include/st-machine-common-stm32mp.inc
In this config file you can select :
+
include conf/machine/include/stm32mp1-mx-config.inc
* boot scheme (by default trusted is set)
+
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
* boot device  (by default sdcard is set)
+
include conf/machine/include/stm32mp1-mx-common.inc
* board (by default eval is set)
 
* name of CubeMX Board DeviceTree files (by default stm32mp157c-defaultmxconfig-mx is commented)
 
* path of CubeMX Board DeviceTree files (by default STM32MP157C-EV1/Templates/DefaultMXConfig/DeviceTree/DefaultMXConfig is commented)
 
   
To select one of each parameter you have just to comment and uncomment lines, and modify CUBEMX_DTB accordingly to the name of CubeMX Board DeviceTree files
+
# =========================================================================
  +
# CubeMX extra config
  +
# =========================================================================
  +
# Set specific path by components for DT file location
  +
CUBEMX_DTB_PATH_TFA    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
  +
CUBEMX_DTB_PATH_UBOOT  = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
  +
CUBEMX_DTB_PATH_LINUX  = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
  +
CUBEMX_DTB_PATH_OPTEEOS = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"
   
===Create symbolic link for EULA with new machine created===
+
# =========================================================================
  +
# User customizing sections
  +
# =========================================================================
  +
 
  +
# Boot Scheme
  +
# =========================================================================
  +
# DISCO / EVAL : basic, trusted or optee
  +
# =========================================================================
  +
#BOOTSCHEME_LABELS += "basic"
  +
#BOOTSCHEME_LABELS += "trusted"
  +
#BOOTSCHEME_LABELS += "optee"
  +
 
  +
# Boot Device Choice
  +
# =========================================================================
  +
# DISCO : sdcard
  +
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
  +
# =========================================================================
  +
# Define the boot device supported
  +
#BOOTDEVICE_LABELS += "sdcard"
  +
 
  +
# WARNING: configs below are only available with EVAL board
  +
#BOOTDEVICE_LABELS += "emmc"
  +
#BOOTDEVICE_LABELS += "nand-4-256"
  +
#BOOTDEVICE_LABELS += "nor-emmc"
  +
#BOOTDEVICE_LABELS += "nor-nand-4-256"
  +
#BOOTDEVICE_LABELS += "nor-sdcard"
  +
 
  +
# Board Type Choice
  +
# =========================================================================
  +
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
  +
# EVAL  : stm32mp157c-ev1
  +
# =========================================================================
  +
# Define the board reference devicetree name
  +
# WARNING: only one setting allowed
  +
#CUBEMX_BOARD_REFERENCE = "stm32mp157a-dk1"
  +
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-dk2"
  +
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-ev1"
  +
 
  +
# CubeMX Project Config
  +
# =========================================================================
  +
# Assign CubeMX Board devicetree and project path name
  +
#CUBEMX_DTB = "stm32mp157c-my-demo"
  +
#CUBEMX_PROJECT = "STM32MP157C-EV1/my-demo/DeviceTree/my-demo"
  +
</pre>
  +
 
  +
<div class="mw-collapsible mw-collapsed">
  +
For {{EcosystemRelease | revision=1.1.0 | range=and before}}
  +
<div class="mw-collapsible-content">
  +
<pre>
  +
 
  +
#@TYPE: Machine
  +
#@NAME: stm32mp1-mx
  +
#@DESCRIPTION: Configuration for STM32CubeMX generated project
  +
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python
  +
 
  +
include conf/machine/include/st-machine-common-stm32mp.inc
  +
include conf/machine/include/stm32mp1-mx-config.inc
  +
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
  +
include conf/machine/include/stm32mp1-mx-common.inc
  +
 
  +
# =========================================================================
  +
# CubeMX extra config
  +
# =========================================================================
  +
# Set specific path by components for DT file location
  +
CUBEMX_DTB_PATH_pn-tf-a-stm32mp    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
  +
CUBEMX_DTB_PATH_pn-u-boot-stm32mp  = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
  +
CUBEMX_DTB_PATH_pn-linux-stm32mp    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
  +
CUBEMX_DTB_PATH_pn-optee-os-stm32mp = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"
  +
 
  +
# =========================================================================
  +
# User customizing sections
  +
# =========================================================================
   
{{ReviewsComments|DHU W10.2: To support GPU and third party content, you need to accept the EULA.}}
+
# Boot Scheme
{{ReviewsComments|DHU W10.2: "The EULA must have a specific name..." Unclear, I understand that a new EULA must be created using a link, but this is not crystal clear}}
+
# =========================================================================
  +
# DISCO / EVAL : basic, trusted or optee
  +
# =========================================================================
  +
#BOOTSCHEME_LABELS += "basic"
  +
BOOTSCHEME_LABELS += "trusted"
  +
#BOOTSCHEME_LABELS += "optee"
   
For having the support of GPU and thirdparty stuff, you need to accept the EULA and the EULA must have a specific name : name of new machine
+
# Boot Device Choice
  $> cd <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
+
# =========================================================================
  $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>
+
# DISCO : sdcard
  +
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
  +
# =========================================================================
  +
# Define the config labels to use to generate flashlayout file
  +
FLASHLAYOUT_CONFIG_LABELS += "sdcard"
   
==Miscellaneous==
+
# WARNING: configs below are only available with EVAL board
===MACHINEOVERRIDES regular expression===
+
FLASHLAYOUT_CONFIG_LABELS += "emmc"
In each customer machine we retrieve this line:
+
#FLASHLAYOUT_CONFIG_LABELS += "nand-4-256"
MACHINEOVERRIDES .= ":stm32mpcommonmx"
+
#FLASHLAYOUT_CONFIG_LABELS += "nor-sdcard"
  +
#FLASHLAYOUT_CONFIG_LABELS += "nor-emmc"
  +
#FLASHLAYOUT_CONFIG_LABELS += "nor-nand-4-256"
   
A regular expression that resolves to one or more target machines with which a recipe is compatible.<br>
+
# Board Type Choice
  +
# =========================================================================
  +
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
  +
# EVAL  : stm32mp157c-ev1
  +
# =========================================================================
  +
# Define the board reference devicetree name
  +
# WARNING: only one setting allowed
  +
#CUBEMX_DT_FILE_BASE = "stm32mp157a-dk1"
  +
#CUBEMX_DT_FILE_BASE = "stm32mp157c-dk2"
  +
CUBEMX_DT_FILE_BASE = "stm32mp157c-ev1"
   
  +
# CubeMX Project Config
  +
# =========================================================================
  +
# Assign CubeMX Board devicetree and project path name
  +
CUBEMX_DTB = "stm32mp157c-<ProjectName>-mx"
  +
CUBEMX_PROJECT = "<ProjectName>"
   
The impact in the build environment is that recipes can now do things conditionally only on the builds for all mx specific machines: stm32mpcommonmx<br>
+
</pre>
It is very useful in some existing recipes to keep the compatibility for all stm32mp1-<ProjectName>.conf machines.<br>
+
</div></div>
For instance use it like this (as it is done in the recipe <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/recipes-bsp/alsa/alsa-state-stm32mp1.bbappend):
 
SRC_URI_append_stm32mpcommonmx
 
The append will be applied for all machines ''(all stm32mp1-<ProjectName>.conf)'' which include '''MACHINEOVERRIDES .= ":stm32mpcommonmx"'''
 
   
So it avoids to create an append file by customer machine.
+
===Create symbolic link for EULA with new machine created===
  +
To support GPU and third party content, you need to accept the EULA.
  +
So a symbolic link must be created with the EULA existing file and  the new machine :
  +
  $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
  +
  $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>
   
  +
==Miscellaneous==
 
===STM32CubeMX class===
 
===STM32CubeMX class===
 
A dedicated class is provided here :   
 
A dedicated class is provided here :   
Line 87: Line 199:
 
The main goal of this class is to manage any change done by the customer in sub folders mx/<ProjectName>/...
 
The main goal of this class is to manage any change done by the customer in sub folders mx/<ProjectName>/...
   
So if a devicetree file is updated for one or more of components, this change will be taken into account automatically during the next compilation done in the Distribution Package.
+
So if a device tree file is updated for one or more of components, this change will be taken into account automatically during the next compilation done in the Distribution Package.
   
 
==Compile your image with the yocto build process==
 
==Compile your image with the yocto build process==
Line 96: Line 208:
 
   $> bitbake st-image-weston
 
   $> bitbake st-image-weston
 
  The generated images are available on build-openstlinuxweston-stm32mp1-<ProjectName>/tmp-glibc/deploy/images/stm32mp1-<ProjectName>
 
  The generated images are available on build-openstlinuxweston-stm32mp1-<ProjectName>/tmp-glibc/deploy/images/stm32mp1-<ProjectName>
  +
  +
{{Warning | In case build fail for an error in the machine.conf, pay attention to do a -c cleanall prior to relaunch the build after correction }}
  +
  +
  +
<noinclude>
  +
[[Category:Distribution Package]]
  +
{{PublicationRequestId | 10212 (AlainF) | 2019-01-09}}
  +
</noinclude>