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

[quality revision] [quality revision]
m
 

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 STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/

2 Generate device tree[edit]

The principle is that the user generates device tree files from the STM32CubeMX tool.
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/

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

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

Each directory of <ProjectName> contains device tree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).


3 Create a 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 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 machine customization 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)
To select your boot device configuration(s), comment and uncomment the FLASHLAYOUTBOOTDEVICE_CONFIG_LABELS lines.
  • Board Type Choice (default configuration is stm32mp157c-ev1)Support Feature Choice
To select your original device tree configuration, comment and uncomment the CUBEMX_DT_FILE_BASE lines.
CubeMX Project config (default configuration is empty)
additional features to enable on board, uncomment the "MACHINE_FEATURES" proposed lines.
  • Specific firmwares and kernel modules configuration
This section allows user to configure some specificites related to its board hardware.
- KERNEL_MODULE_AUTOLOAD you may need to feed this variable with the list of kernel modules that need to be loaded at boot time, such as 'goodix' for current touch-screen used on STM32MP157C-EV1 evaluation board.
- BLUETOOTH_LIST in case you enable the bluetooth feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g. 'linux-firmware-bluetooth-bcm4343' for STM32MP157C-DK2 discovery board).
- WIFI_LIST in case you enable the wifi feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g.'linux-firmware-bcm43430' for STM32MP157C-DK2 discovery board).
  • CubeMX Project config
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 relative to layer path folder (e.g. <ProjectName>)
mx/STM32MP157C-EV1/my-demo/DeviceTree/my-demo)

In order to give a better view on how to configure these variables, some machine samples are provided to show how to set-up a disco and eval board cubeMX machine: refer to conf/machine/examples from meta-st-stm32mp-addons layer.

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

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>

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 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


==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 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/'''

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

Each directory of <ProjectName> contains device tree files associated to the component directory, here: kernel, u-boot and tf-a (Trusted Firmware-A).<br>


{{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 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 the new machine===
   $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
   $> cp stm32mp1-mx.conf stm32mp1-<ProjectName>.conf

===Edit the new machine file: stm32mp1-<ProjectName>.conf===
In the customer machine file, move to ''User customizing machine customization 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''): To select your boot device configuration(s), comment and uncomment the ''FLASHLAYOUT_CONFIG_BOOTDEVICE_LABELS'' lines.
* '''Board TypeSupport Feature Choice'''(default configuration is ''stm32mp157c-ev1'')
: To select your original device tree configuration, comment and uncomment the ''CUBEMX_DT_FILE_BASE'' lines.
* '''CubeMX Project config''' (default configuration is empty): To select additional features to enable on board, uncomment the "MACHINE_FEATURES" proposed lines.
* '''Specific firmwares and kernel modules configuration
: This section allows user to configure some specificites related to its board hardware.
:- ''KERNEL_MODULE_AUTOLOAD'' you may need to feed this variable with the list of kernel modules that need to be loaded at boot time, such as 'goodix' for current touch-screen used on STM32MP157C-EV1 evaluation board.
:- ''BLUETOOTH_LIST'' in case you enable the bluetooth feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g. 'linux-firmware-bluetooth-bcm4343' for STM32MP157C-DK2 discovery board).
:- ''WIFI_LIST'' in case you enable the wifi feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g.'linux-firmware-bcm43430' for STM32MP157C-DK2 discovery board).
* '''CubeMX Project config''': 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'' relative to layer path folder (e.g. <ProjectName>)
mx/STM32MP157C-EV1/my-demo/DeviceTree/my-demo)
In order to give a better view on how to configure these variables, some machine samples are provided to show how to set-up a disco and eval board cubeMX machine: refer to conf/machine/examples from meta-st-stm32mp-addons layer. 
===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==
===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.

===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 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>


{{ReviewsComments|GeraldB: Thanks to insert more information on the generated images because it can be disturbing to see EVAL or DISCO files generated whereas we just want to compile the mx machine}}
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>
(15 intermediate revisions by 3 users not shown)
Line 30: Line 30:
   
 
===Edit the new machine file: stm32mp1-<ProjectName>.conf===
 
===Edit the new machine file: stm32mp1-<ProjectName>.conf===
In the customer machine file, move to ''User customizing sections'' paragraph to configure your machine:
+
In the customer machine file, move to ''User machine customization sections'' paragraph to configure your machine:
* '''Boot Scheme''' (default configuration is ''trusted'')
+
* '''Boot Scheme'''
 
: To select your boot scheme configuration(s), comment and uncomment the ''BOOTSCHEME_LABELS'' lines.
 
: To select your boot scheme configuration(s), comment and uncomment the ''BOOTSCHEME_LABELS'' lines.
* '''Boot Device Choice''' (default configuration is ''sdcard'')
+
* '''Boot Device Choice'''
: To select your boot device configuration(s), comment and uncomment the ''FLASHLAYOUT_CONFIG_LABELS'' lines.
+
: To select your boot device configuration(s), comment and uncomment the ''BOOTDEVICE_LABELS'' lines.
* '''Board Type Choice''' (default configuration is ''stm32mp157c-ev1'')
+
* '''Support Feature Choice'''
: To select your original device tree configuration, comment and uncomment the ''CUBEMX_DT_FILE_BASE'' lines.
+
: To select additional features to enable on board, uncomment the "MACHINE_FEATURES" proposed lines.
* '''CubeMX Project config''' (default configuration is empty)
+
* '''Specific firmwares and kernel modules configuration
  +
: This section allows user to configure some specificites related to its board hardware.
  +
:- ''KERNEL_MODULE_AUTOLOAD'' you may need to feed this variable with the list of kernel modules that need to be loaded at boot time, such as 'goodix' for current touch-screen used on STM32MP157C-EV1 evaluation board.
  +
:- ''BLUETOOTH_LIST'' in case you enable the bluetooth feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g. 'linux-firmware-bluetooth-bcm4343' for STM32MP157C-DK2 discovery board).
  +
:- ''WIFI_LIST'' in case you enable the wifi feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g.'linux-firmware-bcm43430' for STM32MP157C-DK2 discovery board).
  +
* '''CubeMX Project config'''
 
: You have to uncomment and configure the following variables to set your CubeMX project:
 
: 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_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>)
+
:- ''CUBEMX_PROJECT'' path of CubeMX generated device tree files relative to layer path folder (e.g. mx/STM32MP157C-EV1/my-demo/DeviceTree/my-demo)
  +
In order to give a better view on how to configure these variables, some machine samples are provided to show how to set-up a disco and eval board cubeMX machine: refer to conf/machine/examples from meta-st-stm32mp-addons layer.
   
 
===Create symbolic link for EULA with new machine created===
 
===Create symbolic link for EULA with new machine created===
Line 49: Line 55:
   
 
==Miscellaneous==
 
==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.
 
 
 
===STM32CubeMX class===
 
===STM32CubeMX class===
 
A dedicated class is provided here :   
 
A dedicated class is provided here :   
Line 78: Line 70:
 
  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>
   
{{ReviewsComments|GeraldB: Thanks to insert more information on the generated images because it can be disturbing to see EVAL or DISCO files generated whereas we just want to compile the mx machine}}
+
{{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>
 
<noinclude>