TheSTM32CubeMP2 Package is part of the STM32 MPU embedded software offer. It runs on the Arm® Cortex®-M33 coprocessor and Arm® Cortex®-M0+ coprocessor.
It is included in the three software packages proposed by the Linux® Yocto-based embedded software:
- in the starter package as pre-built examples (firmware),
- in the developer package as full source code for development (associated with an IDE),
- in the distribution package as a dedicated recipe (that integrates the full source code) in the OpenSTLinux distribution.
Therefore, this article explains how to develop, build and run existing or new examples thanks to these three software packages.
1. Prerequisites[edit | edit source]
In the next chapters, it is assumed that the selected board is assembled according to the information provided in its hardware description article (e.g., STM32MP257x-EV1 - hardware description for STM32MP257x-EV1 Evaluation boards), and that the different boot related switches of the board are also known (e.g., boot related switches for STM32MP257x-EV1 Evaluation boards).
Refer also to the Which Package better suits your needs article for further information on all packages.
The firmware is loaded into the Arm® Cortex®-M33 or Arm® Cortex®-M0+ coprocessor by the Arm® Cortex®-A35 processor running the Linux® distribution making use of the Linux Remote Proc framework. This method is also referred to as Production Mode
- Refer to Coprocessor_management_overview article to get an overview of mechanisms to put in place to design software in the multiprocessor system.
2. Starter Package for STM32CubeMP2[edit | edit source]
This chapter, and its sub-chapters, aims to explain how you can compile an existing Cube example and then load and get it running on Cortex-M33 code.
2.1. Starter Package prerequisites[edit | edit source]
Refer to the Starter Package for STM32MP25 Eval Board for all the information describing how to install the Starter Package.
- Please note that in order to run the cube examples on CM33 you must flash the OSTL images using the FlashLayout_<boot_storage>_<board_name>-ca35tdcid-ostl-m33-examples-optee.tsv
- This image layout ensures that the correct images with the appropriate RIF configuration of the peripherals used by M33 is present.
2.2. User file system for Arm® Cortex®-M33 examples[edit | edit source]
The folder structure of Linux User File System for STM32Cube M33 firmware is described below for STM32MP257F-EV1 board:
3. Developer Package for STM32CubeMP2[edit | edit source]
The STM32MPU Developer Package article explains how to get the source code for the STM32CubeMP2 Package, and the associated tools (e.g., IDE).
This chapter and its sub-chapters aim to explain all steps needed to run an existing example using STM32CubeIDE. Once done, you can jump to the chapter #How to go further with the Developer Package to enhance your experience with the STM32CubeMP2 Developer Package.
3.1. Developer Package prerequisites[edit | edit source]
- Refer to the Installing the STM32CubeMP2 Package to obtain and install the source code
- Refer to the new recommended IDE: STM32CubeIDE
3.2. How to build and run an existing example with the STM32CubeIDE[edit | edit source]
- Here we take example of a project OpenAMP_TTY_echo available on STM32MP257F-EV1 board. You can use any other example which is available on the MP2x board that you are using.
- Open the Projects Folder containing the example and double-click on file .project to open Eclipse IDE:
- Below figure explains a typical layout of a cube firmware project developed with STM32CubeIDE
- Select a config and press hammer button to build the example
- Firmware binaries must be signed before they can be executed on the co-processor.
3.3. How to run examples[edit | edit source]
- After you have built the signed firmware binary as shown in the previous section, it should be copied and executed on the Coprocessor.
 Information
|
| Please use FlashLayout_<boot_storage>_<board_name>-ca35tdcid-ostl-m33-examples-optee.tsv to execute CubeFw M33 examples to have the correct Optee RIF configuration: IP used by examples allocated to CID2. |
3.3.1. Copy built firmware to correct directory in the target filesystem (STM32 board)[edit | edit source]
- When system boots from flash (production mode), the USB port can be connected to your host machine and it would appear as a device with IP address: 192.168.7.1
- From a GitBash Shell (On Windows) or Terminal Windows (on a Linux machine) of your host PC, run the following commands to copy the Firmware on to the target.
$ ssh root@192.168.7.1 'mkdir -p /usr/local/Cube-M33-examples/STM32MP257F-EV1/Applications/OpenAMP_TTY_echo/lib/firmware' $ scp Projects/STM32MP257F-EV1/Applications/OpenAMP/OpenAMP_TTY_echo/STM32CubeIDE/CM33/NonSecure/CA35TDCID_m33_ns_sign/OpenAMP_TTY_echo_CM33_NonSecure_sign.bin root@192.168.7.1:/usr/local/Cube-M33-examples/STM32MP257F-EV1/Applications/OpenAMP_TTY_echo/lib/firmware/ $ scp Utilities/scripts/fw_cortex_m33.sh root@192.168.7.1:/usr/local/Cube-M33-examples/STM32MP257F-EV1/Applications/OpenAMP_TTY_echo/
- Above commands assume that the project is an Application and its name is OpenAMP_TTY_echo, you can replace these strings with your project type(Examples or Applications) and the corresponding name.
3.3.2. Starting the example firmware[edit | edit source]
- Once copied to the target, the firmware can be run by executing the script as follows:
cd /usr/local/Cube-M33-examples/STM32MP257F-EV1/Applications/OpenAMP_TTY_echo/ ./fw_cortex_m33.sh start fw_cortex_m33.sh: fmw_name=OpenAMP_TTY_echo_CM33_NonSecure_sign.bin Stopping running fw ... [ 1232.784799] remoteproc remoteproc0: stopped remote processor m33 [ 1232.795058] remoteproc remoteproc0: powering up m33 [ 1232.801334] remoteproc remoteproc0: Booting fw image OpenAMP_TTY_echo_CM33_NonSecure_sign.bin, size 34440 [ 1232.806431] rproc-virtio rproc-virtio.10.auto: assigned reserved memory node vdev0buffer@812fa000 [ 1232.815436] virtio_rpmsg_bus virtio0: rpmsg host is online [ 1232.820030] rproc-virtio rproc-virtio.10.auto: registered virtio0 (type 7) [ 1232.826673] remoteproc remoteproc0: remote processor m33 is now up [ 1232.833005] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty addr 0x400 [ 1232.840724] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty addr 0x401
3.3.3. Stopping the example firmware[edit | edit source]
cd /usr/local/Cube-M33-examples/STM32MP257F-EV1/Applications/OpenAMP_TTY_echo/ ./fw_cortex_m33.sh stop [ 2290.481170] remoteproc remoteproc0: warning: remote FW shutdown without ack [ 2290.482719] remoteproc remoteproc0: stopped remote processor m33 [2]+ Done cat /dev/ttyRPMSG1 [1]+ Done cat /dev/ttyRPMSG0
3.4. How to go further with the Developer Package[edit | edit source]
3.4.1. How to develop on Arm® Cortex®-M33[edit | edit source]
3.4.1.1. Create your project for your board[edit | edit source]
A project is board and application specific. To create a new project, you may start from any available project from Examples or Applications
| Information
|
|
All Examples have following characteristics:
- It contains the source code of HAL, CMSIS and BSP drivers which are the minimum components required to develop a code for a given board.
- It contains the include paths for all the firmware components.
- It defines the STM32MP25 supported device, which defines the CMSIS and HAL driver configuration settings.
- It provides pre-configured user files which are ready-to-use as shown below:
- HAL initialized with default time base with ARM Core SysTick.
- SysTick ISR implemented for delay management purpose (HAL_Delay()).
| Information
|
|
3.4.1.2. Add middleware to your project (optional)[edit | edit source]
Your project may need to support additional middleware. This support is available from these middleware stacks: OpenAMP and FreeRTOS.
Refer to the documentation to understand which middleware source files have to be used.
If you have the experience, it is also possible to look in the application source code to find out which source files and which include paths must be added.
- Applications for board STM32MP257F-EV1 : Projects/STM32MP257F-EV1/Applications
3.4.1.3. Configure the firmware components[edit | edit source]
The HAL and middleware components offer a set of build time configuration options using macros #define, declared in a header file. A template configuration file is provided for each component. It has to be copied to the project folder (usually the configuration file is named xxx_conf_template.h, and the word ‘_template’ needs to be removed when copying it to the project folder).
The configuration file provides enough information to understand the impact of each configuration option. More detailed information is available in the documentation provided with each component.
3.4.1.4. Start the HAL Library[edit | edit source]
After jumping to the main program, the application code must call the function HAL_Init() to initialize the HAL Library. It includes the following tasks:
a) Configuration of the SysTick to generate an interrupt every 1 millisecond with the SysTick interrupt priority TICK_INT_PRIO defined in the file stm32mp2xx_hal_conf.h.
- In production mode, the SysTick clock is already configured by FSBL running on Arm® Cortex®-A35.
b) Set NVIC Group Priority to 0.
c) Call to the HAL_MspInit() function defined in the stm32mp2xx_hal_msp.c user file performs global low-level hardware initializations like HSEM clock enable.
3.4.1.5. Initialize the peripheral[edit | edit source]
a) Edit the file stm32mp2xx_hal_msp.c to write to the peripheral HAL_PPP_MspInit() function. Proceed as follows:
- Enable the peripheral clock.
- Configure the peripheral GPIOs.
- Configure the DMA channel and enable DMA interrupt (if needed).
- Enable peripheral interrupt (if needed).
b) Edit the stm32xxx_it.c file to call on the required interrupt handlers (peripheral and DMA), if needed.
c) Write process complete callback functions if you plan to use peripheral interrupt or DMA.
d) In the main.c file, initialize the peripheral handler structure then call the function HAL_PPP_Init() to initialize your peripheral.
3.4.1.6. Develop your application[edit | edit source]
At this stage, your system is ready and you can start developing your application code.
- The HAL provides intuitive and ready-to-use APIs to configure the peripheral. It supports polling, interrupts and a DMA programming model, to accommodate any application requirement.
- For more details on how to use each peripheral and how to manage real-time constraints, refer to the full set of examples and applications provided in the STM32CubeMP2 Package (List of available projects)
3.4.2. How to tweak RIF settings for your projects[edit | edit source]
Application for Displaying on LTDC Layer 3 shows how you can modify the RIF settings and reserve LTDC Layer 3 to be used by Cotex-M33.
4. Distribution Package for STM32CubeMP2[edit | edit source]
The Linux Yocto-based distribution package (STM32MPU Distribution Package) integrates the STM32CubeMP2 Package source code in a dedicated recipe in the OpenSTLinux distribution. It allows to build all the examples provided in the STM32CubeMP2 Package and generates a Linux Yocto-based embedded software in which all examples (firmware) are integrated in the Linux file system.
This chapter and its sub-chapters aim to explain all steps needed to run an existing example using the Distribution Package. Once done, you can jump to the chapter #How to go further with the Distribution Package to enhance your experience with the STM32CubeMP2 Distribution Package.
4.1. Distribution Package prerequisites[edit | edit source]
- OpenSTLinux Distribution Package article gives further information about the OpenSTLinux distribution.
- Installing the OpenSTLinux distribution article explains how to install and initialize the OpenSTLinux environment.
Refer also to
- STM32 MPU OpenSTLinux layer article for further information about the dedicated M33 project recipe (named m33projects-stm32mp2)
- OpenEmbedded_-_devtool article for further information related to devtool largely used in these chapters.
4.2. m33projects recipe[edit | edit source]
All M33 firmware (Examples) are provided inside a dedicated recipe named m33projects in the OpenSTLinux distribution
Find below the OpenSTLinux and M33projects structure:
- OpenSTLinux structure :
openstlinux-<release_version> OpenSTLinux distribution ├── layers/meta-openembedded Collection of layers for the OpenEmbedded-Core universe (OpenEmbedded standard) ├── layers/meta-qt5 QT5 layer for OpenEmbedded (standard) ├── layers/meta-st │ ├── meta-st-openstlinux STMicroelectronics layer that contains the frameworks and images settings for the OpenSTLinux distribution │ ├── meta-st-stm32mp STMicroelectronics layer that contains the description of the BSP for the STM32MP devices │ │ ├── recipes-bsp │ │ │ ├── alsa Recipes for ALSA control configuration │ │ │ ├── drivers Recipes for Vivante GCNANO GPU kernel drivers │ │ │ ├── trusted-firmware-a Recipes for TF-A │ │ │ └── u-boot Recipes for U-Boot │ │ ├── recipes-connectivity │ │ │ └── wifi Recipes for Wifi │ │ ├── recipes-extended │ │ │ ├── linux-examples Recipes to manage Linux examples for Cortex-A │ │ │ ├── m4coredump Recipes to manage coredump for Cortex-M │ │ │ └── m33projects Recipes to manage STM32CubeMP2 Package examples and applications within the OpenSTLinux distribution │ │ ├── recipes-graphics │ │ │ ├── gcnano-userland Recipes for Vivante libraries OpenGL ES, OpenVG and EGL (multi backend) │ │ │ └── [...] │ │ ├── recipes-kernel │ │ │ ├── linux Recipes for Linux kernel │ │ │ └── linux-firmware Recipes for Linux firmwares (example, Bluetooth firmware) │ │ ├── recipes-security │ │ │ └── optee Recipes for OPTEE │ │ ├── recipes-st │ │ │ └── images Recipes for the bootfs and userfs partitions binaries │ │ └── [...] │ ├── meta-st-stm32mp-addons STMicroelectronics layer that helps managing the STM32CubeMX integration │ └── scripts │ ├── envsetup.sh Environment setup script for Distribution Package │ └── [...] └── openembedded-core Core metadata for current versions of OpenEmbedded (standard)
- M33projects structure :
openstlinux-<release_version> OpenSTLinux distribution ├── layers/meta-st │ ├── meta-st-stm32mp STMicroelectronics layer that contains the description of the BSP for the STM32MP2 devices │ │ ├── recipes-extended │ │ │ ├── m33projects Recipes for STM32CubeMP2 Package within the OpenSTLinux distribution │ │ │ │ ├── files │ │ │ │ │ ├── fw_cortex_m0.sh Script to load and run firmware on the target for Cortex-M0+ │ │ │ │ │ ├── fw_cortex_m33.sh Script to load and run firmware on the target for Cortex-M33 │ │ │ │ │ ├── shutdown-stm32mp2-m33.sh │ │ │ │ │ ├── st-m33firmware-load-default.sh │ │ │ │ │ └── st-m33firmware-load.service │ │ │ │ ├── m33projects.inc Definition of rules to be applied to build/install Firmwares and scripts in Linux File System │ │ │ │ └── m33projects-stm32mp2.bb List of examples splitted according to supported boards
This recipe is in charge of:
- building all examples and applications listed in m33projects.bb and initially located in Firmware/Projects/<Board_name> from STM32CubeMP2 Package source code
- installing built examples in the Linux File System (/usr/local/Cube-M33-examples/), including all generated firmware binaries (elf files), the script to start/stop the firmware (fw_cortex_m33.sh) and a README file for each example
/usr/local/Cube-M33-examples/
|-- <BOARD_NAME> (ie STM32MP257F-EV1)
|-- <EXAMPLE_TYPE> (ie Examples or Applications)
|-- <PROJECT_NAME> (ie USBPD_DRP_UCSI)
|-- fw_cortex_m33.sh
|-- README
|--lib
|--firmware
|-- ELF file for <BOARD_NAME> (ie USBPD_DRP_UCSI_CM33_NonSecure_stripped.elf)
|-- <BOARD_NAME> (ie STM32MP257F-DK)
...
4.3. How to get STM32CubeMP2 package software[edit | edit source]
To retrieve the source code, you need to follow the steps described below, once you have initialized and built the OpenSTLinux environment for the first time:
- Go into your workspace
cd openstlinux-<release_version>
- Call devtool with the name of the recipe you want to retrieve (m33projects-stm32mp2), and specify a location in which to load the source code (sources/m33projects-stm32mp2)
devtool modify m4projects-stm32mp2 sources/m33projects-stm32mp2
- Check status
devtool status NOTE: Starting bitbake server... m33projects-stm32mp2: <path_to_your_workspace>/sources/m33projects-stm32mp2
- Go in STM32CubeMP2 Firmware source code
cd <path_to_your_workspace>/sources/m33projects-stm32mp2
m33projects-stm32mp2 ├── COPYING ├── Drivers │ ├── BSP │ ├── CMSIS │ └── STM32MP2xx_HAL_Driver ├── _htmresc ├── Middlewares │ └── Third_Party ├── package.xml ├── Projects │ ├── STM32CubeProjectsList.html │ ├── STM32MP257F-DK │ └── STM32MP257F-EV1 ├── Release_Notes.html └── Utilities └── ResourcesManager
| Information
|
|
4.4. How to develop/modify/build/download an existing example without OpenEmbedded[edit | edit source]
4.5. How to go further with the Distribution Package[edit | edit source]
4.5.1. How to add a new example with OpenEmbedded[edit | edit source]
The list of examples to be included in the Linux File System is defined in the file m33projects-stm32mp2.bb of the recipe m33projects
- go into recipe m33projects
cd <path_to_your_workspace>/layers/meta-st/meta-st-stm32mp/recipes-extended/m33projects
- Edit the file m33projects-stm32mp2.bb and add your new example to be built according to the Core(CM33 or CM0+) and the board you want to use (EVAL/EVx or DISCO/DKx)
PROJECTS_LIST_M33 = " \ STM32MP257F-EV1/Demonstrations/USBPD_DRP_UCSI \ STM32MP257F-EV1/Demonstrations/LowPower_SRAM_Demo \ 'STM32MP257F-EV1/Examples/TIM/TIM_MyFirmware' <- Adding new example TIM_MyFirmware \ STM32MP257F-DK/Demonstrations/USBPD_DRP_UCSI \ STM32MP235F-DK/Demonstrations/USBPD_DRP_UCSI \ STM32MP215F-DK/Demonstrations/OpenAMP/OpenAMP_TTY_echo \ "
PROJECTS_LIST_M0 = " \ STM32MP257F-EV1/Demonstrations/CM0PLUS_Demo \ "
4.5.2. How to rebuild the examples with OpenEmbedded[edit | edit source]
If you need to provide a new software Linux image with a Linux file system updated with your changes, follow the instructions below:
- Make your changes in STM32MP2 Firmware source code (in <path_to_your_workspace>/sources/m33projects-stm32mp2/stm32cube_fw_mp2)
- Go to the build folder
cd <path_to_your_workspace>/build-<name_of_distro>
- Clean the m33projects build folder
bitbake m33projects-stm32mp2 -f -c cleanall
- Rebuild the recipe m33projects
bitbake m33projects-stm32mp2
- Rebuild the image
bitbake st-image-weston
4.5.3. How to download an image[edit | edit source]
- Refer to Flashing the built image to obtain all information on how to Flash a new image on the STM32MP2 board.
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.