View source for STM32MP1 Developer Package

This article describes how to get and use the '''Developer Package''' of the '''STM32MPU Embedded Software''' for any development platform of the '''STM32MP1 family''' ([[STM32MP15 boards]]), in order to modify some of its pieces of software, or to add applications on top of it. 

It lists some '''prerequisites''' in terms of knowledges and development environment, and gives the '''step-by-step''' approach to download and install the STM32MPU Embedded Software components for this Package.

Finally, it proposes some guidelines to upgrade (add, remove, configure, improve...) any piece of software.

==Developer Package content==
If you are not yet familiar with the '''STM32MPU Embedded Software''' distribution and its '''Packages''', please read the following articles:
* [[Which STM32MPU Embedded Software Package better suits your needs]] (and especially the [[Which STM32MPU Embedded Software Package better suits your needs#Developer Package|Developer Package]] chapter)
* [[STM32MPU Embedded Software distribution]]
If you are already familiar with the Developer Package for the STM32MPU Embedded Software distribution, [[#Fast links to essential commands|the fast links to essential commands]] might interest you.


To sum up, this '''Developer Package''' provides:
* for the '''OpenSTLinux distribution''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-A processor):
** the '''software development kit''' (SDK), based on Yocto SDK, for cross-development on an host PC
** the following pieces of software in '''source code''':
*** Linux<sup>&reg;</sup> kernel
*** U-Boot
*** Trusted Firmware-A (TF-A)
*** optionally, Open source Trusted Execution Environment (OP-TEE)
** the '''debug symbol files''' for Linux<sup>&reg;</sup> kernel, U-Boot and TF-A
* for the '''STM32Cube MPU Package''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M processor):
** all pieces of software (BSP, HAL, middlewares and applications) in '''source code'''
** the '''integrated development environment (IDE)''' (STM32CubeIDE)
Note that, the application frameworks for the OpenSTLinux distribution are not available as source code in this Package.

{{ReviewsComments|JCT W815: the STM32CubeMX tool shall be added in the list above when it will be fully integrated in this article}}

[[File: STM32_MPU_Embedded_Software_Developer_Package.png|thumb|upright=2|center|link=|Components of the Developer Package]]

==Developer Package step-by-step overview==
{{highlight|'''The steps to get the STM32MPU Embedded Software Developer Package ready for your developments, are:'''}} <br>
<span style="font-size:21px">☐</span> [[#Checking the prerequisites|Checking the prerequisites]] <br>
<span style="font-size:21px">☐</span> [[#Installing the Starter Package|Installing the Starter Package for your board]] <br>

<span style="font-size:21px">☐</span> Installing the components to develop software running on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-A (OpenSTLinux distribution)
:<span style="font-size:21px">☐</span> [[#Installing the SDK|Installing the SDK]] ('''mandatory''' for any development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-A) <br>
:<span style="font-size:21px">☐</span> [[#Installing the Linux kernel|Installing the Linux kernel]] ('''mandatory only''' if you plan to modify the Linux kernel or to add external out-of-tree Linux kernel modules) <br>
:<span style="font-size:21px">☐</span> [[#Installing the U-Boot|Installing the U-Boot]] ('''mandatory only''' if you plan to modify the U-Boot) <br>
:<span style="font-size:21px">☐</span> [[#Installing the TF-A|Installing the TF-A]] ('''mandatory only''' if you plan to modify the TF-A)<br>
:<span style="font-size:21px">☐</span> [[#Installing the TF-A SPP|Installing the TF-A-SSP]] ('''mandatory only''' if you plan to modify the TF-A SSP)<br>
:<span style="font-size:21px">☐</span> [[#Installing the debug symbol files|Installing the debug symbol files]] ('''mandatory only''' if you plan to debug Linux<sup>&reg;</sup> kernel, U-Boot or TF-A with GDB)<br>

<span style="font-size:21px">☐</span> Installing the components to develop software running Arm Cortex-M (STM32Cube MPU Package)
:<span style="font-size:21px">☐</span> [[#Installing STM32CubeIDE|Installing STM32CubeIDE]] ('''mandatory''' for any development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M) <br>
:<span style="font-size:21px">☐</span> [[#Installing the STM32Cube MPU Package|Installing the STM32Cube MPU Package]] ('''mandatory only''' if you plan to modify the Cube firmware) <br>


Once these steps are achieved, you are able to:
* develop software running on Arm Cortex-A
** [[#Modifying the Linux kernel|Modifying the Linux kernel]]
** [[#Adding external out-of-tree Linux kernel modules|Adding external out-of-tree Linux kernel modules]]
** [[#Adding Linux user space applications|Adding Linux user space applications]]
** [[#Modifying the U-Boot|Modifying the U-Boot]]
** [[#Modifying the TF-A|Modifying the TF-A]]
* [[#Developing software running on Arm Cortex-M4|develop software running on Arm Cortex-M4]]

==Checking the prerequisites==
===Knowledges===
The STM32MP1 Developer Package aims at enriching a Linux-based software for the targeted product: basic knowledges about Linux are recommended to make the most of this Package.

Having a look at the [[STM32MPU Embedded Software architecture overview]] is also highly recommended.

===Development setup===
{{:Development setup for STM32MPU Embedded Software}}

==Installing the Starter Package==
Before developing with the Developer Package, {{highlight|it is essential to start up your board thanks to its '''Starter Package'''}}. All articles relative to Starter Packages are found in [[:Category:Starter Package]]: find the one that corresponds to your board, and follow the installation instructions (if not yet done), before going further.

In brief, it means that:
* your board boots successfully
* the flashed image comes from the same release of the STM32MPU Embedded Software distribution than the components that will be downloaded in this article

Thanks to the Starter Package, '''all [[STM32MP15 Flash mapping#Flash partitions|Flash partitions]] are populated'''.

Then, with the Developer Package, it is possible to modify or to upgrade the partitions independently one from the others.

For example, if you only want to modify the Linux kernel (part of ''bootfs'' partition), installing the SDK and the Linux kernel are enough; no need to install anything else.

==Installing the components to develop software running on Arm Cortex-A (OpenSTLinux distribution)==

===Installing the SDK===
{{Highlight|Optional step}}''': it is mandatory only if you want to modify or add software running on Arm Cortex-A (e.g. Linux kernel, Linux user space applications...).'''

The SDK for OpenSTLinux distribution provides a stand-alone cross-development toolchain and libraries tailored to the contents of the specific image flashed in the board. If you want to know more about this SDK, please read the [[SDK for OpenSTLinux distribution]] article.
{{:STM32MP1 Developer Package - SDK}}

{{Warning|Now that the SDK is installed, please do not move or rename the ''<SDK installation directory>''.}}
====Starting up the SDK====
{{highlight|'''The SDK environment setup script must be run once in each new working terminal in which you cross-compile:'''}}
 {{PC$}} source <SDK installation directory>/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi


The following checkings allow to ensure that the environment is correctly setup:
* Check the target architecture 
 {{PC$}} echo $ARCH
 arm
* Check the toolchain binary prefix for the target tools
 {{PC$}} echo $CROSS_COMPILE
 arm-ostl-linux-gnueabi-
* Check the C compiler version
 {{PC$}} $CC --version
 arm-ostl-linux-gnueabi-gcc (GCC) <GCC version>
 [...]
* Check that the SDK version is the expected one
 {{PC$}} echo $OECORE_SDK_VERSION
 <expected SDK version>

If any of these commands fails or does not return the expected result, please try to reinstall the SDK.

===Installing the Linux kernel===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the Linux kernel (configuration, device tree, driver...), or to add external out-of-tree Linux kernel modules.'''

Prerequite: the [[#Installing the SDK|SDK is installed]].

====Downloading the Linux kernel====
{{:STM32MP1 Developer Package - Linux kernel}}

====Building and deploying the Linux kernel for the first time====
'''It is mandatory to execute once the steps specified below before modifying the Linux kernel, or adding external out-of-tree Linux kernel modules.'''

The partitions related to the Linux kernel are:
* the ''bootfs'' partition that contains the Linux kernel U-Boot image (''uImage'') and device tree
* the ''rootfs'' partition that contains the Linux kernel modules

The Linux kernel might be cross-compiled, either in the source code directory, or in a dedicated directory different from the source code directory.<br>
This last method is recommended as it clearly separates the files generated by the cross-compilation from the source code files.
{{Info|The {{CodeSource | meta-st-stm32mp | recipes-kernel/linux/linux-stm32mp/README.HOW_TO.txt | README_HOWTO.txt}} helper file is '''THE''' reference for the Linux kernel build}}
{{Warning|[[#Starting up the SDK|The SDK must be started]]}}


{{highlight|'''Open the ''<Linux kernel installation directory>/README.HOW_TO.txt'' helper file, and execute its instructions to:'''}} <br>
<span style="font-size:21px">☐</span> setup a software configuration management (SCM) system (''git'') for the Linux kernel (optional but recommended) <br>
<span style="font-size:21px">☐</span> prepare the Linux kernel (applying the ST patches) <br>
<span style="font-size:21px">☐</span> configure the Linux kernel (applying the ST fragments) <br>
<span style="font-size:21px">☐</span> cross-compile the Linux kernel <br>
<span style="font-size:21px">☐</span> deploy the Linux kernel (i.e. update the software on board) <br>


'''The Linux kernel is now installed''': let's [[#Modifying the Linux kernel|modify the Linux kernel]], or [[#Adding external out-of-tree Linux kernel modules|add external out-of-tree Linux kernel modules]].

===Installing the U-Boot===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the U-Boot.'''

Prerequite: the [[#Installing the SDK|SDK is installed]].

====Downloading the U-Boot====
{{:STM32MP1 Developer Package - U-Boot}}

====Building and deploying the U-Boot for the first time====
'''It is mandatory to execute once the steps specified below before modifying the U-Boot.'''

As explained in the [[Boot chain overview|boot chain overview]], the trusted boot chain is the default solution delivered by STMicroelectronics.

Within this scope, the partition related to the U-Boot is the ''ssbl'' one that contains the U-Boot and its device tree blob. 
{{Info|The {{CodeSource | meta-st-stm32mp | recipes-bsp/u-boot/u-boot-stm32mp/README.HOW_TO.txt | README_HOWTO.txt}} helper file is '''THE''' reference for the U-Boot build}}
{{Warning|[[#Starting up the SDK|The SDK must be started]]}}


{{highlight|'''Open the ''&#60;U-Boot installation directory>/README.HOW_TO.txt'' helper file, and execute its instructions to:'''}} <br>
<span style="font-size:21px">☐</span> setup a software configuration management (SCM) system (''git'') for the U-Boot (optional but recommended) <br>
<span style="font-size:21px">☐</span> prepare the U-Boot (applying the ST patches) <br>
<span style="font-size:21px">☐</span> cross-compile the U-Boot <br>
<span style="font-size:21px">☐</span> deploy the U-Boot (i.e. update the software on board) <br>


'''The U-Boot is now installed''': let's [[#Modifying the U-Boot|modify the U-Boot]].

===Installing the TF-A===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the TF-A.'''

Prerequite: the [[#Installing the SDK|SDK is installed]].

====Downloading the TF-A====
{{:STM32MP1 Developer Package - TF-A}}

====Building and deploying the TF-A for the first time====
'''It is mandatory to execute once the steps specified below before modifying the TF-A.'''

As explained in the [[Boot chain overview|boot chain overview]], the trusted boot chain is the default solution delivered by STMicroelectronics.

Within this scope, the partition related to the TF-A is the ''fsbl'' one.
{{Info|The {{CodeSource | meta-st-stm32mp | recipes-bsp/trusted-firmware-a/tf-a-stm32mp/README.HOW_TO.txt | README_HOWTO.txt}} helper file is '''THE''' reference for the TF-A build}}
{{Warning|[[#Starting up the SDK|The SDK must be started]]}}


{{highlight|'''Open the ''<TF-A installation directory>/README.HOW_TO.txt'' helper file, and execute its instructions to:'''}} <br>
<span style="font-size:21px">☐</span> setup a software configuration management (SCM) system (''git'') for the TF-A (optional but recommended) <br>
<span style="font-size:21px">☐</span> prepare the TF-A (applying the ST patches) <br>
<span style="font-size:21px">☐</span> cross-compile the TF-A <br>
<span style="font-size:21px">☐</span> deploy the TF-A (i.e. update the software on board) <br>


'''The TF-A is now installed''': let's [[#Modifying the TF-A|modify the TF-A]].

===Installing the TF-A-SSP===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the TF-A to use [[Security_overview#Secure_Secret_Provisioning|Secure Secret provisioning]] feature.'''

Prerequite: the [[#Installing the SDK|SDK is installed]].

====Downloading the TF-A-SSP====
{{:STM32MP1 Developer Package - TF-A-SSP}}

====Building the TF-A-SSP for the first time====
'''It is mandatory to execute once the steps specified below before modifying the TF-A SSP.'''

{{Info|The {{CodeSource | meta-st-stm32mp | recipes-bsp/trusted-firmware-a/tf-a-stm32mp/README.HOW_TO.txt | README_HOWTO.txt}} helper file is '''THE''' reference for the TF-A SSP build}}
{{Warning|[[#Starting up the SDK|The SDK must be started]]}}


{{highlight|'''Open the ''<TF-A SSP installation directory>/README.HOW_TO.txt'' helper file, and execute its instructions to:'''}} <br>
<span style="font-size:21px">☐</span> setup a software configuration management (SCM) system (''git'') for the TF-A SSP (optional but recommended) <br>
<span style="font-size:21px">☐</span> prepare the TF-A SSP (applying the ST patches) <br>
<span style="font-size:21px">☐</span> cross-compile the TF-A SSP <br>


'''The TF-A SSP is now built'''.

===Installing the OP-TEE===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the OP-TEE.'''

Prerequite: the [[#Installing the SDK|SDK is installed]].

{{ReviewsComments|YCO 15-Feb-19 : We should to write that we need here an optee image flashed on the board, extra partitions are created for TEE. We can put this info as prerequisite in  OP-TEE.README.HOW_TO.txt}}

====Downloading the OP-TEE====
{{:STM32MP1 Developer Package - OP-TEE}}

====Building and deploying the OP-TEE for the first time====
'''It is mandatory to execute once the steps specified below before modifying the OP-TEE.'''

As explained in the [[Boot chain overview|boot chain overview]], the trusted boot chain is the default solution delivered by STMicroelectronics.
{{ReviewsComments|YCO 15-Feb-19 : fsbl is not the right partition, partition are teeh,teed,teex in a optee image mapping  }}
Within this scope, the partition related to the OP-TEE is the ''fsbl'' one.

{{Info|The {{CodeSource | meta-st-stm32mp | recipes-security/optee/optee-os/README.HOW_TO.txt | README_HOWTO.txt}} helper file is '''THE''' reference for the OP-TEE build}}
{{Warning|[[#Starting up the SDK|The SDK must be started]]}}


{{highlight|'''Open the ''<OP-TEE installation directory>/README.HOW_TO.txt'' helper file, and execute its instructions to:'''}} <br>
<span style="font-size:21px">☐</span> setup a software configuration management (SCM) system (''git'') for the OP-TEE (optional but recommended) <br>
<span style="font-size:21px">☐</span> prepare the OP-TEE (applying the ST patches) <br>
<span style="font-size:21px">☐</span> cross-compile the OP-TEE <br>
<span style="font-size:21px">☐</span> deploy the OP-TEE (i.e. update the software on board) <br>


'''The OP-TEE is now installed''': let's [[#Modifying the OP-TEE|modify the OP-TEE]].

{{ReviewsComments|YCO 15-Feb-19 : This link doesn't give extra information to modify the OP-TEE, see my remark at this link  }}

===Installing the debug symbol files===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to debug Linux<sup>&reg;</sup> kernel, U-Boot or TF-A with GDB.'''

====Downloading the debug symbol files====
{{:STM32MP1 Developer Package - debug symbol files}}

====Using the debug symbol files====
These files are used to debug the Linux<sup>&reg;</sup> kernel, U-Boot or TF-A with [[GDB]]. Especially, the [[GDB#Debug OpenSTLinux BSP components|Debug OpenSTLinux BSP components]] chapter explains how to load the debug symbol files in GDB.

==Installing the components to develop software running on Arm Cortex-M4 (STM32Cube MPU Package)==

===Installing STM32CubeIDE===
{{Highlight|Optional step}}''': it is needed if you want to modify or add software running on Arm Cortex-M.'''

The table below explains how to download and install STM32CubeIDE which addresses STM32 MCU, and also provides support for Cortex-M inside STM32 MPU.
{{:STM32CubeIDE release note}}

===Installing the STM32Cube MPU Package===
{{highlight|'''Optional step'''}}''': it is mandatory only if you want to modify the STM32Cube MPU Package.'''

Prerequite: the [[#Installing STM32CubeIDE|STM32CubeIDE is installed]].

{{:STM32MP1 Developer Package - STM32CubeMP1 Package}}


'''The STM32Cube MPU Package is now installed''': let's [[#Developing software running on Arm Cortex-M4|develop software running on Arm Cortex-M4]].

==Developing software running on Arm Cortex-A7==
{{:Cross-compile with OpenSTLinux SDK}}

==Developing software running on Arm Cortex-M4==

===How to create a Cube project from scratch or open/modify an existing one from STM32Cube MPU package===
Please refer to [[STM32CubeMP1 Package#Developer Package for STM32CubeMP1|STM32CubeMP1 Package]] article.

== Fast links to essential commands==
If you are already familiar with the Developer Package for the STM32MPU Embedded Software distribution, fast links to the essential commands are listed below.
{{Info|With the links below, you will be redirected to other articles; use the ''back'' button of your browser to come back to these fast links}}
{| class="st-table"
! Link to the command
|-
|'''Starter Packages'''{{UpdateNeededForNewBoard|Point to the "Fast links to essential commands" of the new board Starter Package}}
|-
|[[STM32MP15 Evaluation boards - Starter Package#Fast links to essential commands|Essential commands of the STM32MP15 Evaluation board Starter Package]]
|-
|[[STM32MP15 Discovery kits - Starter Package#Fast links to essential commands|Essential commands of the STM32MP15 Discovery kit Starter Package]]
|-
| | '''SDK'''
|-
| [[STM32MP1 Developer Package - SDK#Download|Download and install the latest SDK]]
|-
| [[#Starting up the SDK|Start the SDK]]
|-
| | '''Linux kernel'''
|-
| [[STM32MP1 Developer Package - Linux kernel#Download|Download and install the latest Linux kernel]]
|-
| {{CodeSource | meta-st-stm32mp | recipes-kernel/linux/linux-stm32mp/README.HOW_TO.txt | Helper file for the '''Linux kernel''' build, and update on board}}
|-
| | '''U-Boot'''
|-
| [[STM32MP1 Developer Package - U-Boot#Download|Download and install the latest U-Boot]]
|-
| {{CodeSource | meta-st-stm32mp | recipes-bsp/u-boot/u-boot-stm32mp/README.HOW_TO.txt | Helper file for the '''U-Boot''' build, and update on board}}
|-
| | '''TF-A'''
|-
| [[STM32MP1 Developer Package - TF-A#Download|Download and install the latest TF-A]]
|-
| {{CodeSource | meta-st-stm32mp | recipes-bsp/trusted-firmware-a/tf-a-stm32mp/README.HOW_TO.txt | Helper file for the '''TF-A''' build, and update on board}}
|-
| | '''TF-A SSP'''
|-
| [[STM32MP1 Developer Package - TF-A-SSP#Download|Download and install the latest TF-A SSP]]
|-
| {{CodeSource | meta-st-stm32mp | recipes-bsp/trusted-firmware-a/tf-a-stm32mp/README.HOW_TO.txt | Helper file for the '''TF-A SSP''' build, and update on board}}
|-
| | '''OP-TEE'''
|-
| [[STM32MP1 Developer Package - OP-TEE#Download|Download and install the latest OP-TEE]]
|-
| {{CodeSource | meta-st-stm32mp | recipes-security/optee/optee-os/README.HOW_TO.txt | Helper file for the '''OP-TEE''' build, and update on board}}
|-
|| '''Linux user space'''
|-
| [[How to cross-compile with the Developer Package#Adding a "hello world" user space example|Simple user space application]]
|-
|| '''STM32Cube MPU Package'''
|-
| [[STM32MP1 Developer Package - STM32CubeMP1 Package#Download|Download and install the latest STM32CubeMP1 Package]]
|-
| [[STM32CubeMP1 Package#Developer Package for STM32CubeMP1 |Create or modify a Cube project]] 
|}

==How to go further?==
Now that your developments are ready, you might want to switch to the [[STM32MP1 Distribution Package]], in order to create your own distribution and to generate your own SDK and image.

<noinclude>
{{PublicationRequestId | 8418 | 2018-08-14 | AlainF}}

[[Category:Getting started with STM32MP1 boards]]
[[Category:Developer Package]]

{{UpdateNeededForNewRelease|
* Check that the following transcluded articles deal with the last ecosystem release, and that the "Release note" row of these transcluded articles refer to their "Archives" section (see details in the "Contributors:Ecosystem release delivery" article)
{{:STM32MP1 Developer Package - SDK}}
{{:STM32MP1 Developer Package - Linux kernel}}
{{:STM32MP1 Developer Package - U-Boot}}
{{:STM32MP1 Developer Package - TF-A}}
{{:STM32MP1 Developer Package - OP-TEE}}
{{:STM32MP1 Developer Package - debug symbol files}}
{{:STM32MP1 Developer Package - STM32CubeMP1 Package}}
* Make the modifications indicated by {{UpdateNeededForNewRelease}}
}}
</noinclude>