Last edited 2 years ago

STM32CubeMP1 Package

1. Introduction to STM32Cube[edit source]

STM32Cube™ provides comprehensive embedded software libraries and tools, significantly reducing development effort, time and cost.

STM32Cube™ is fully integrated in STM32MPU_Embedded_Software_distribution and consists of (usable together or independently):

  • The Hardware Abstraction Layer (HAL), enabling portability between different STM32 devices via standardized API calls
  • The Low-Layer API (LL), a light-weight, optimized, expert oriented set of APIs designed for runtime efficiency and so enhanced performance
  • A collection of Middleware components, like FreeRTOS, OpenAMP (depending on the MPU series)
  • A collection of Examples, running on an MPU board and allowing demonstration of a basic implementation of features from a set of IPs
  • Configuration and C code generation for pin multiplexing, clock tree, peripherals and middleware setup with graphical wizards
  • Generation of IDE-ready projects for an integrated development environment tool chain
  • Direct import of STM32 Cube embedded software libraries from st.com
  • Integrated updater to keep STM32CubeMX up-to-date

2. STM32CubeMP1 package overview[edit source]

The STM32CubeMP1 Package(also named STM32Cube Firmware Package) is the embedded software part of STM32Cube™, running on the Arm® Cortex®-M processor (for example Arm Cortex-M4).


Info white.png Information
Note:

3. Software architecture overview[edit source]

The STM32CubeMP1 Package is based on the STM32Cube MCU package but has been adapted to a Linux Framework (OpenSTLinux).

STM32CubeMP1 Package introduces new components such as OpenAMP and RessourceManager that allow easy communication and ressource sharing between main processors running with Linux on Cortex A, and MCU coprocessors running on Cortex M.

  • OpenAMP is a library implementing the remote processor service framework (RPMsg) which is a virtio-based messaging bus that allows a local processor to communicate with remote processors available on the system.
  • ResourceManager is a utility that handles peripheral-accessibility requests and system-resource configuration.
Info white.png Information
Note:

The figure below gives an overview of the STM32CubeMP1_architecture.

STM32CubeMPUPackageArchitecture.png

Info white.png Information
Note:

4. STM32CubeMP1 Package Content[edit source]

STM32CubeMP1 Package offers a highly portable Hardware Abstraction Layer (HAL), built around a generic and modular architecture. Moreover it offers a full support for all the STM32MP1 Series devices.

This HAL allows the upper layers, middleware and application, to implement functions independently of the STM32MP1 device used. This improves the library code re-usability and guarantees easy portability from one device to another.

STM32CubeMP1 Package also offers a highly portable Low Layer interface (LL), which allows a quick, simple and optimized API to access the STM32MP1 registers.

4.1. Overview[edit source]

The STM32CubeMP1 Package is provided with the structure shown below.

STM32CubeMPUPackageStructurev3.png


4.2. Drivers[edit source]

The Drivers folder contains all the STM32Cube Drivers, including BSP and HAL drivers

Info white.png Information
Note:

The STM32CubeMP1 Package provides all driver user manuals:

  • The BSP user manual for EVAL board is available in STM32Cube_FW_MP1\Drivers\BSP\STM32MP15xx_EVAL : STM32MP15xx_EVAL_BSP_User_Manual.chm
  • The BSP user manual for DISCO board is available in STM32Cube_FW_MP1\Drivers\BSP\STM32MP15xx_DISCO : STM32MP15xx_DISCO_BSP_User_Manual.chm
  • The HAL user manual is available in STM32Cube_FW_MP1\Drivers\STM32MP1xx_HAL_Driver : STM32MP157Cxx_CM4_User_Manual.chm

4.3. Middlewares[edit source]

The Middlewares folder contains all available STM32Cube Middlewares including FreeRTOS and OpenAMP

Info white.png Information
Note:

4.4. Projects[edit source]

The Projects folder contains all STM32Cube Examples that are classified in 3 levels as described below :

  • Level 0 : Examples. It uses only the HAL drivers without any middleware component. They are available in directory Firmware/Projects/<board_name>/Examples.
  • Level 1 : Applications. It provides typical use cases of each middleware component. They are available in directory Firmware/Projects/<board_name>/Applications.
  • Level 2 : Demonstrations. It involves all the HAL, BSP and middleware components. They are available in directory Firmware/Projects/<board_name>/Demonstrations


A Template folder is available in Firmware/Projects/<board_name>/Templates and allows quick creation and building of any firmware application on a given board.

All examples respect the same structure :

   ├── OpenAMP_TTY_echo
   │   ├── readme.txt               describes the example behavior and the setup required to make it work
   │   ├── Inc                      contains all header files
   │   ├── Remoteproc               (optional): contains specific files related to the use of Linux® remote processor framework to load STM32Cube Cortex-M firmware
   │   ├── Src                      contains all the sources code files
   │   └── SW4STM32                 contains the preconfigured project for Eclipse IDE

4.4.1. List of projects[edit source]

You will find below a list of examples, applications and demonstrations available for STM32MP1 boards (STM32MP157C-EV1 and STM32MP157C-DK2) :

Info white.png Information
Note:


  • Examples, applications and demonstrations for STM32MP157C-EV1
   ├── STM32MP157C-EV1                             Legend:             
   │   ├── Applications                                Examples added since ecosystem release ≥ v1.2.0 
   │   │   ├── CoproSync                               Examples added since ecosystem release ≥ v1.1.0 
   │   │       ├── CoproSync_ShutDown
   │   │   ├── FreeRTOS
   │   │       ├── FreeRTOS_ThreadCreation
   │   │   └── OpenAMP
   │   │       ├── OpenAMP_Dynamic_ResMgr
   │   │       ├── OpenAMP_FreeRTOS_echo
   │   │       ├── OpenAMP_raw
   │   │       ├── OpenAMP_TTY_echo
   │   │       └── OpenAMP_TTY_echo_wakeup
   │   ├── Demonstrations
   │   │   └── AI_Character_Recognition
   │   ├── Examples
   │   │   ├── ADC
   │   │   │   └── ADC_SingleConversion_TriggerTimer_DMA
   │   │   ├── Cortex
   │   │   │   └── CORTEXM_MPU
   │   │   ├── CRC
   │   │   │   └── CRC_UserDefinedPolynomial
   │   │   ├── CRYP
   │   │   │   └── CRYP_AES_DMA
   │   │   ├── DAC
   │   │   │   └── DAC_SimpleConversion
   │   │   ├── DMA
   │   │   │   └── DMA_FIFOMode
   │   │   ├── FDCAN
   │   │   │   └── FDCAN_Loopback
   │   │   ├── GPIO
   │   │   │   └── GPIO_EXTI
   │   │   ├── HASH
   │   │   │   └── HASH_SHA224SHA256_DMA
   │   │   ├── I2C
   │   │   │   ├── I2C_TwoBoards_ComDMA
   │   │   │   └── I2C_TwoBoards_ComIT
   │   │   ├──  LPTIM
   │   │   │   └──  LPTIM_PulseCounter
   │   │   ├── PWR
   │   │   │   └── PWR_STOP_CoPro
   │   │   ├── QSPI
   │   │   │   └── QSPI_ReadWrite_IT
   │   │   ├── SPI
   │   │   │   ├── SPI_FullDuplex_ComDMA_Master
   │   │   │   └── SPI_FullDuplex_ComDMA_Slave
   │   │   ├── TIM
   │   │   │   └── TIM_DMABurst
   │   │   ├── UART
   │   │   │   └── UART_Receive_Transmit_Console
   │   │   │   └── UART_TwoBoards_ComIT
   │   │   └── WWDG
   │   │       └── WWDG_Example
  • Examples, applications and demonstrations for STM32MP157C-DK2
   ├── STM32MP157C-DK2                             Legend:             
   │   ├── Applications                                Examples added since ecosystem release ≥ v1.2.0 
   │   │   ├── CoproSync                               Examples added since ecosystem release ≥ v1.1.0 
   │   │       ├── CoproSync_ShutDown
   │   │   ├── FreeRTOS
   │   │       ├── FreeRTOS_ThreadCreation
   │   │   └── OpenAMP
   │   │       ├── OpenAMP_FreeRTOS_echo
   │   │       ├── OpenAMP_raw
   │   │       ├── OpenAMP_TTY_echo
   │   │       └── OpenAMP_TTY_echo_wakeup
   │   ├── Demonstrations
   │   │   └── AI_Character_Recognition
   │   ├── Examples
   │   │   ├── ADC
   │   │   │   └── ADC_SingleConversion_TriggerTimer_DMA
   │   │   ├── Cortex
   │   │   │   └── CORTEXM_MPU
   │   │   ├── CRC
   │   │   │   └── CRC_UserDefinedPolynomial
   │   │   ├── CRYP
   │   │   │   └── CRYP_AES_DMA
   │   │   ├── DMA
   │   │   │   └── DMA_FIFOMode
   │   │   ├── FDCAN
   │   │   │   └── FDCAN_Loopback
   │   │   ├── GPIO
   │   │   │   └── GPIO_EXTI
   │   │   ├── HASH
   │   │   │   └── HASH_SHA224SHA256_DMA
   │   │   ├── I2C
   │   │   │   └── I2C_TwoBoards_ComIT
   │   │   ├── LPTIM
   │   │   │   └── LPTIM_PulseCounter
   │   │   ├── PWR
   │   │   │   └── PWR_STOP_CoPro
   │   │   ├── SPI
   │   │   │   ├── SPI_FullDuplex_ComDMA_Master
   │   │   │   ├── SPI_FullDuplex_ComDMA_Slave
   │   │   │   ├── SPI_FullDuplex_ComIT_Master
   │   │   │   └── SPI_FullDuplex_ComIT_Slave
   │   │   ├── TIM
   │   │   │   └── TIM_DMABurst
   │   │   ├── UART
   │   │   │   └── UART_Receive_Transmit_Console
   │   │   │   ├── UART_TwoBoards_ComDMA
   │   │   │   └── UART_TwoBoards_ComIT
   │   │   └── WWDG
   │   │       └── WWDG_Example

5. Getting started with STM32CubeMP1 Package[edit source]

STM32CubeMP1 Package is delivered with STM32MPU Embedded Software distribution and is then provided in the 3 software packages: Starter Package, Developer Package and Distribution Package.

  • Starter Package: provides pre-built examples, applications and demonstration firmware (for demo only).
  • Developer Package: provides the full STM32CubeMP1 source code for development, including dedicated tools (IDE and so on).
  • Distribution Package: it provides the full integration of STM32CubeMP1 package in OpenSTLinux distribution for software distribution.

5.1. Prerequisites[edit source]

In the following sections, we take the assumption that you have already installed all the materials related to the package for your board. Please read the following notes carefully:

5.2. Introduction to boot mode[edit source]

The STM32MP1 can be run in 2 differents boot modes : Production boot mode (default mode) and Engineering boot mode

  • Production boot mode: Firmware is loaded into the coprocessor by the master processor (Cortex A7 - Flash Memory boot mode), this means:
  • System ressources are managed directly by OpenSTLinux (clocks, regulators, and so on)
  • the pre-built pieces of firmware are provided/downloaded in an OpenSTLinux image or file system
  • the pre-built firmware is launched on the coprocessor through the Linux Remote Proc component
  • Cortex-A firmware (Linux OS) is in charge of loading the Cortex-M firmware
Info white.png Information
Notes: At boot time, you can select 3 kernel configurations:
  • Configuration 1 (<board_name>-sdcard): All IPs are assigned to Cortex-A7 for Linux drivers, Cortex-M4 coprocessor firmware TTY executed by default
  • This is the configuration activated by default
  • Configuration 2 (<board_name>-a7-examples-sdcard): Some IPs are assigned to Cortex-A7 to execute Cortex-A7 delivered examples on the board (EVAL or DISCO).
  • Configuration 3 (<board_name>-m4-examples-sdcard): Some IPs are assigned to Cortex-M4 to execute Cortex-M4 delivered examples on the board (EVAL or DISCO).

Example for STM32MP157C-DK2 board:

Select the boot mode
1:      stm32mp157c-dk2-sdcard
2:      stm32mp157c-dk2-a7-examples-sdcard
3:      stm32mp157c-dk2-m4-examples-sdcard
  • Engineering boot mode is used specifically for firmware testing directly on the coprocessor, this means:
  • all ressources are managed directly in the example source code (clocks, regulators, and so on)
  • the firmware can be loaded directly from your favorite IDE

Most of the examples can be used in Engineering boot mode (except those that require firmware running on a Cortex-A7, such as the OpenAMP examples)

Info white.png Information
Notes:

5.3. Introduction to user file system for M4 examples[edit source]

The folder structure of Linux User File System for STM32Cube M4 firmware is described below for each STM32MP1 board (STM32MP157C-EV1 and STM32MP157C-DK2):


STM32CubeMPUPackageLinuxStructurev.png

5.4. Starter Package for STM32CubeMP1[edit source]

Starter Package allows you to launch and run, on an M4 core, a set of examples from Linux console (How_to_get_Terminal). These examples are available in the Linux File System (userfs: /usr/local), and have been built with the STM32Cube MP1 software Package (pre-built firmwares)

Info white.png Information
Notes:
  • Examples running on an M4 core are called Firmware
  • Firmware is located in folder /usr/local/Cube-M4-examples/<board_name>/Examples
  • A script fw_cortex_m4.sh is provided to start/stop the firmware in the M4 core.

5.4.1. Prerequisites[edit source]

Warning white.png Warning
Please make sure that you have installed the Starter Package related to your STM32MP1 board

5.4.2. How to run the examples[edit source]

After Flashing images onto your board, you need to open a Linux console (please refer to How_to_get_Terminal), and follow the steps below:

5.4.2.1. Select boot mode for m4 examples[edit source]

When booting the Linux image, you need to select a dedicated device tree configuration for m4 examples, which allows the allocation of specific clock and pin control assignments related to M4 examples.

This means that you need to select the boot mode stm32mp157c-ev1-m4-examples-sdcard during the U-Boot stage, as described in the following log:

U-Boot 2018.11-stm32mp-19-01-04 (Jan 04 2019 - 09:59:10 +0000)
CPU: STM32MP157CAA Rev.B
Model: STMicroelectronics STM32MP157C eval daughter on eval mother
Board: stm32mp1 in trusted mode (st,stm32mp157c-ev1)
Board: MB1263 Var1 Rev.C-01
...
...
Found /mmc0_stm32mp157c-ev1_extlinux/extlinux.conf
Retrieving file: /mmc0_stm32mp157c-ev1_extlinux/extlinux.conf
616 bytes read in 1 ms (601.6 KiB/s)
Retrieving file: /mmc0_stm32mp157c-ev1_extlinux/../splash.bmp
46180 bytes read in 3 ms (14.7 MiB/s)
Select the boot mode
1:      stm32mp157c-ev1-sdcard
2:      stm32mp157c-ev1-a7-examples-sdcard
3:      stm32mp157c-ev1-m4-examples-sdcard           <- Select stm32mp157c-ev1-m4-examples-sdcard
Enter choice: 3
3:      stm32mp157c-ev1-m4-examples-sdcard
Retrieving file: /uImage
5.4.2.2. Select examples or applications related to your board[edit source]
 cd /usr/local/Cube-M4-examples/<board_name>


  • Example of output log:
root@stm32mp1:/usr/local/Cube-M4-examples/STM32MP157C-EV1# ls -l *
Applications:
total 3
drwxr-xr-x 3 root root 1024 Mar  9  2018 CoproSync
drwxr-xr-x 3 root root 1024 Mar  9  2018 FreeRTOS
drwxr-xr-x 5 root root 1024 Mar  9  2018 OpenAMP

Demonstrations:
total 1
drwxr-xr-x 3 root root 1024 Mar  9  2018 AI_Character_Recognition

Examples:
total 15
drwxr-xr-x 3 root root 1024 Mar  9  2018 ADC
drwxr-xr-x 3 root root 1024 Mar  9  2018 CRC
drwxr-xr-x 3 root root 1024 Mar  9  2018 CRYP
drwxr-xr-x 3 root root 1024 Mar  9  2018 Cortex
drwxr-xr-x 3 root root 1024 Mar  9  2018 DAC
drwxr-xr-x 3 root root 1024 Mar  9  2018 DMA
drwxr-xr-x 3 root root 1024 Mar  9  2018 GPIO
drwxr-xr-x 3 root root 1024 Mar  9  2018 HASH
drwxr-xr-x 4 root root 1024 Mar  9  2018 I2C
drwxr-xr-x 3 root root 1024 Mar  9  2018 PWR
drwxr-xr-x 3 root root 1024 Mar  9  2018 QSPI
drwxr-xr-x 4 root root 1024 Mar  9  2018 SPI
drwxr-xr-x 3 root root 1024 Mar  9  2018 TIM
drwxr-xr-x 3 root root 1024 Mar  9  2018 UART
drwxr-xr-x 3 root root 1024 Mar  9  2018 WWDG
5.4.2.3. Select the example or application to run[edit source]
  • For an example use the following command:
 cd /usr/local/Cube-M4-examples/<board_name>/Examples/<example_type>/<example_to_run>
  • For an Application use the following command :
 cd /usr/local/Cube-M4-examples/<board_name>/Applications/<application_type>/<application_to_run>
                                    |-- fw_cortex_m4.sh
                                    |-- README
                                    |--lib
                                        |--firmware
                                            |-- ELF file for <board_name>
  • fw_cortex_m4.sh : script to start / stop firmware
  • README  : all information about example
  • Example output log:
root@stm32mp1:/usr/local/Cube-M4-examples/STM32MP157C-EV1/Examples/QSPI/QSPI_ReadWrite_IT# ls -l
total 8
-rwxr-xr-x 1 root root 5513 Aug 31  2018 README
-rwxr-xr-x 1 root root  854 Aug 31  2018 fw_cortex_m4.sh
drwxr-xr-x 3 root root 1024 Aug 31  2018 lib

root@stm32mp1:/usr/local/Cube-M4-examples/STM32MP157C-EV1/Examples/QSPI/QSPI_ReadWrite_IT# ls -l lib/firmware/
total 26
-rwxr-xr-x 1 root root 210364 Mar  9  2018 QSPI_ReadWrite_IT.elf
5.4.2.4. Read the README file carefully[edit source]

It provides all the information about the example setup and verdict

5.4.2.5. Start the firmware[edit source]

Use the following command to start the selected example:

 ./fw_cortex_m4.sh start
  • Example output log:
root@stm32mp1:/usr/local/Cube-M4-examples/STM32MP157C-EV1/Examples/QSPI/QSPI_ReadWrite_IT# ./fw_cortex_m4.sh start
fw_cortex_m4.sh: fmw_name=QSPI_ReadWrite_IT.elf
[16876.378399] remoteproc remoteproc0: powering up m4
[16876.382908] remoteproc remoteproc0: Booting fw image QSPI_ReadWrite_IT.elf, size 210104
[   82.822243] remoteproc remoteproc0: header-less resource table
[   82.827069] remoteproc remoteproc0: not resource table found for this firmware
[   82.834064] remoteproc remoteproc0: header-less resource table
[   82.873522] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Linked as a consumer to regulator.9
[   82.943959] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:timer@40000000 (ops 0xc0bd47f0)
[   82.958620] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:serial@4000f000 (ops 0xc0bd47f0)
[   82.979759] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:i2c@40015000 (ops 0xc0bd47f0)
[   82.990388] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:dac@40017000 (ops 0xc0bd47f0)
[   83.001066] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:timer@44000000 (ops 0xc0bd47f0)
[   83.010866] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:spi@44004000 (ops 0xc0bd47f0)
[   83.020759] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:dma@48001000 (ops 0xc0bd47f0)
[   83.035481] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:adc@48003000 (ops 0xc0bd47f0)
[   83.044288] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:hash@4c002000 (ops 0xc0bd47f0)
[   83.055075] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:rng@4c003000 (ops 0xc0bd47f0)
[   83.065018] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:crc@4c004000 (ops 0xc0bd47f0)
[   83.075279] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:cryp@4c005000 (ops 0xc0bd47f0)
[   83.085529] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:qspi@58003000 (ops 0xc0bd47f0)
[   83.095857] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:button (ops 0xc0bd47f0)
[   83.105563] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:m4_led (ops 0xc0bd47f0)
[   83.117791] remoteproc remoteproc0: remote processor m4 is now up
5.4.2.6. Stop the firmware[edit source]

Use the following command to stop the example that is running:

 ./fw_cortex_m4.sh stop
  • Example output log:
root@stm32mp1:/usr/local/Cube-M4-examples/STM32MP157C-EV1/Examples/QSPI/QSPI_ReadWrite_IT# ./fw_cortex_m4.sh stop
fw_cortex_m4.sh: fmw_name=QSPI_ReadWrite_IT.elf
[  320.965374] remoteproc remoteproc0: warning: remote FW shutdown without ack
[  320.978380] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Dropping the link to regulator.9
[  320.996540] remoteproc remoteproc0: stopped remote processor m4
  • This stops the firmware using the Linux Remote Processor component
  • It releases the relevant ressource settings used by the example

5.5. Developer Package for STM32CubeMP1[edit source]

Developer Package provides all the STM32Cube MPU source code and tools.


Info white.png Information
Notes:
  • Please refer to the STM32MP15 reference manuals for all information about STM32MP1, and in particular the IP you might want to modify in order to ensure coherency and capabilities

5.5.1. Prerequisites[edit source]

  • Please refer to the new preferred IDE: STM32CubeIDE (or to the SW4STM32 IDE[1] inherited from the first release)
Warning white.png Warning
  • Please be sure to have installed the STM32CubeMP1Package, STM32CubeIDE or SW4STM32 IDE
  • Please be sure to have run Starter Package for STM32CubeMP1 in Production mode
  • Please be sure to have connected ST-Link and Ethernet cables to your board

5.5.2. How to use the Eclipse IDE with an existing example[edit source]

5.5.2.1. How to rebuild an example[edit source]
  • Open the folder containing the example and double-click on file .project to open Eclipse IDE:

IDE ExampleOpenv2.png

IDE ExampleOpen.png

  • Click on following button to build the example:

IDE ExampleBuild.png

5.5.2.2. How to download and run an example[edit source]
Info white.png Information
Note:
  • All Firmware is downloaded with the SW4STM32 IDE in the Linux File System in /usr/local/projects
  • Open the Serial Console to check the IP address of the board:

IDE ExampleSerialConsole.png

  • Open the Debug Configurations panel:

IDE ExampleDebugMenu.png

  • Configure the Main panel to add the firmware binary:

IDE ExampleDebugPanelMain.png

  • Configure the Startup panel to load and run the Firmware in the target:
Info white.png Information
Note:
  • To work in Enginneering mode, you need to:

IDE ExampleDebugPanelStartup.png

IDE ExampleDebugPanelLoadFw.png

IDE ExampleRunning.png

5.5.2.3. How to start/stop an example[edit source]
  • Locate path where the firmware has been loaded

IDE ExampleConsole.png

  • Use a script to start/stop the firmware

IDE ExampleConsoleStartStop.png

5.6. Distribution Package for STM32CubeMP1[edit source]

Distribution Package provides all the STM32MCube MPU source code integrated in OpenSTLinux_distribution. It allows you to build all the examples provided in the STM32CubeMP1 Package and generate a full distribution based on Linux OS. All example binaries (or firmware) are integrated in the Linux file system.

Warning white.png Warning
The Distribution Package is not a developpement environment as it is based on the OpenEmbedded environement. OpenEmbedded is a build framework that is used to create Linux distributions for embedded devices.

5.6.1. Prerequisites[edit source]

Warning white.png Warning
Please make sure that you have installed the OpenSTLinux Distribution Package and that you have initialized and built the environment for the first time

5.6.2. Introduction to m4projects recipe[edit source]

All M4 firmware (Examples) are provided inside a dedicated recipe named m4projects in the OpenSTLinux distribution

Please find below the OpenSTLinux and M4projects 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 STM32MP1 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
│   │   │   └── m4projects           Recipes to manage STM32CubeMP1 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)
  • M4projects structure :
openstlinux-<release_version>        OpenSTLinux distribution
├── layers/meta-st
│   ├── meta-st-stm32mp              STMicroelectronics layer that contains the description of the BSP for the STM32MP1 devices
│   │   ├── recipes-extended
│   │   │   ├── m4projects           Recipes for STM32CubeMP1 Package within the OpenSTLinux distribution
│   │   │   │   ├── files
│   │   │   │   │   ├── Makefile.stm32                    Makefile used to build M4 examples
│   │   │   │   │   ├── parse_project_config.py           Specific parser to retrieve examples names / board names and paths
│   │   │   │   │   ├── st-m4firmware-load-default.sh   
│   │   │   │   │   └── st-m4firmware-load.service
│   │   │   │   ├── m4projects.inc                        Definition of rules to be applied to build/install Firmwares and scripts in Linux File System
│   │   │   │   └── m4projects-stm32mp1.bb                List of examples splitted according to supported boards

This recipe is in charge of:

  • building all examples and applications listed in m4projects.bb and initially located in Firmware/Projects/<Board_name> from STM32CubeMP1 Package source code
  • installing built examples in the Linux File System (/usr/local/Cube-M4-examples/), including all generated firmware binaries (elf files), the script to start/stop the firmware (fw_cortex_m4.sh) and a README file for each example
        /usr/local/Cube-M4-examples/
                     |-- <BOARD_NAME> (ie STM32MP157C-EV1)
                         |-- <EXAMPLE_TYPE> (ie Examples or Applications)
                            |-- <PROJECT_NAME> (ie OpenAMP_TTY_echo)
                                    |-- fw_cortex_m4.sh
                                    |-- README
                                    |--lib
                                        |--firmware
                                            |-- ELF file for <BOARD_NAME> (ie OpenAMP_TTY_echo.elf)
                     |-- <BOARD_NAME> (ie STM32MP157C-DK2)
                             ...

5.6.3. How to retrieve the STM32CubeMP1 source code[edit source]

5.6.3.1. Introduction to the devtool utility[edit source]

The STM32CubeMP1 source code is already included in the OpenSTLinux distribution, but the source code is not directly visible nor available for development purposes. To retrieve the source code, we need to use the devtool utility, which is provided in the environment.

Info white.png Information
Note:
  • Please refer to the Devtool Utility to obtain further information on how to retrieve source code from the OpenSTLinux environment

For more information on devtool you can use the following command :

 devtool --help
 NOTE: Starting bitbake server...
 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
               [--color COLOR] [-h]
               <subcommand> ...

OpenEmbedded development tool

options:
  --basepath BASEPATH  Base directory of SDK / build directory
  --bbpath BBPATH      Explicitly specify the BBPATH, rather than getting it
                       from the metadata
  -d, --debug          Enable debug output
  -q, --quiet          Print only errors
  --color COLOR        Colorize output (where COLOR is auto, always, never)
  -h, --help           show this help message and exit

subcommands:
  Beginning work on a recipe:
    add                  Add a new recipe
    modify               Modify the source for an existing recipe
    upgrade              Upgrade an existing recipe
  Getting information:
    status               Show workspace status
    search               Search available recipes
  Working on a recipe in the workspace:
    build                Build a recipe
    rename               Rename a recipe file in the workspace
    edit-recipe          Edit a recipe file in your workspace
    find-recipe          Find a recipe file in your workspace
    configure-help       Get help on configure script options
    update-recipe        Apply changes from external source tree to recipe
    reset                Remove a recipe from your workspace
    finish               Finish working on a recipe in your workspace
  Testing changes on target:
    deploy-target        Deploy recipe output files to live target machine
    undeploy-target      Undeploy recipe output files in live target machine
    build-image          Build image including workspace recipe packages
  Advanced:
    create-workspace     Set up workspace in an alternative location
    import               Import exported tar archive into workspace
    extract              Extract the source for an existing recipe
    sync                 Synchronize the source tree for an existing recipe
    export               Export workspace into a tar archive
Use devtool <subcommand> --help to get help on a specific command
5.6.3.2. Retrieve the source code[edit source]

To retrieve the source code, you need to follow the steps described below once you have initalized 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 (m4projects-stm32mp1), and specify a location in which to load the source code (sources/m4projects-stm32mp1)
 devtool modify m4projects-stm32mp1 sources/m4projects-stm32mp1
  • Check status
 devtool status
NOTE: Starting bitbake server...
m4projects-stm32mp1: <path_to_your_workspace>/sources/m4projects-stm32mp1
  • Go in STM32CubeMP1 Firmware source code
 cd <path_to_your_workspace>/sources/m4projects-stm32mp1

m4projects-stm32mp1
    ├── COPYING
    ├── Drivers
    │   ├── BSP
    │   ├── CMSIS
    │   └── STM32MP1xx_HAL_Driver
    ├── _htmresc
    ├── Middlewares
    │   └── Third_Party
    ├── package.xml
    ├── Projects
    │   ├── STM32CubeProjectsList.html
    │   ├── STM32MP157C-DK2
    │   └── STM32MP157C-EV1
    ├── Release_Notes.html
    └── Utilities
       └── ResourcesManager
Info white.png Information
Note:

5.6.4. How to develop/modify/build/download an example without OpenEmbedded[edit source]

As the STM32CubeMP1 source code and structure is exactly the same as that provided in the Developer Package, you can develop / modify / build and download an example by following description of Developer_Package for STM32CubeMP1

5.6.5. How to add a new example with OpenEmbedded[edit source]

The list of examples to be included in the Linux File System is defined in the file m4projects-stm32mp1.bb of the recipe m4projects

  • go into recipe m4projects
 cd <path_to_your_workspace>/layers/meta-st/meta-st-stm32mp/recipes-extended/m4projects


  • Edit the file m4projects-stm32mp1.bb and add your new example to be built according to the board you want to use (EVAL/EVx or DISCO/DKx)
PROJECTS_LIST_EVAL = " \
'STM32MP157C-EV1/Examples/ADC/ADC_SingleConversion_TriggerTimer_DMA' \
'STM32MP157C-EV1/Examples/Cortex/CORTEXM_MPU' \
'STM32MP157C-EV1/Examples/CRYP/CRYP_AES_DMA' \
'STM32MP157C-EV1/Examples/CRC/CRC_UserDefinedPolynomial' \
'STM32MP157C-EV1/Examples/DAC/DAC_SimpleConversion' \
'STM32MP157C-EV1/Examples/DMA/DMA_FIFOMode' \
'STM32MP157C-EV1/Examples/GPIO/GPIO_EXTI' \
'STM32MP157C-EV1/Examples/HASH/HASH_SHA224SHA256_DMA' \
'STM32MP157C-EV1/Examples/I2C/I2C_TwoBoards_ComDMA' \
'STM32MP157C-EV1/Examples/I2C/I2C_TwoBoards_ComIT' \
'STM32MP157C-EV1/Examples/PWR/PWR_STOP_CoPro' \
'STM32MP157C-EV1/Examples/QSPI/QSPI_ReadWrite_IT' \
'STM32MP157C-EV1/Examples/SPI/SPI_FullDuplex_ComDMA_Master/' \
'STM32MP157C-EV1/Examples/SPI/SPI_FullDuplex_ComDMA_Slave/' \
'STM32MP157C-EV1/Examples/TIM/TIM_DMABurst' \
'STM32MP157C-EV1/Examples/TIM/TIM_MyFirmware'        <- Adding new example TIM_MyFirmware
'STM32MP157C-EV1/Examples/UART/UART_TwoBoards_ComIT' \
'STM32MP157C-EV1/Examples/UART/UART_Receive_Transmit_Console' \
'STM32MP157C-EV1/Examples/WWDG/WWDG_Example' \
'STM32MP157C-EV1/Applications/FreeRTOS/FreeRTOS_ThreadCreation' \
'STM32MP157C-EV1/Applications/OpenAMP/OpenAMP_Dynamic_ResMgr' \
'STM32MP157C-EV1/Applications/OpenAMP/OpenAMP_raw' \
'STM32MP157C-EV1/Applications/OpenAMP/OpenAMP_TTY_echo' \
'STM32MP157C-EV1/Applications/OpenAMP/OpenAMP_TTY_echo_wakeup' \
'STM32MP157C-EV1/Applications/CoproSync/CoproSync_ShutDown' \
'STM32MP157C-EV1/Demonstrations/AI_Character_Recognition' \
"
PROJECTS_LIST_DISCO = " \
'STM32MP157C-DK2/Examples/ADC/ADC_SingleConversion_TriggerTimer_DMA' \
'STM32MP157C-DK2/Examples/Cortex/CORTEXM_MPU' \
'STM32MP157C-DK2/Examples/CRYP/CRYP_AES_DMA' \
'STM32MP157C-DK2/Examples/CRC/CRC_UserDefinedPolynomial' \
'STM32MP157C-DK2/Examples/DMA/DMA_FIFOMode' \
'STM32MP157C-DK2/Examples/GPIO/GPIO_EXTI' \
'STM32MP157C-DK2/Examples/HASH/HASH_SHA224SHA256_DMA' \
'STM32MP157C-DK2/Examples/I2C/I2C_TwoBoards_ComIT' \
'STM32MP157C-DK2/Examples/LPTIM/LPTIM_PulseCounter' \
'STM32MP157C-DK2/Examples/PWR/PWR_STOP_CoPro' \
'STM32MP157C-DK2/Examples/SPI/SPI_FullDuplex_ComDMA_Master' \
'STM32MP157C-DK2/Examples/SPI/SPI_FullDuplex_ComDMA_Slave' \
'STM32MP157C-DK2/Examples/SPI/SPI_FullDuplex_ComIT_Master' \
'STM32MP157C-DK2/Examples/SPI/SPI_FullDuplex_ComIT_Slave' \
'STM32MP157C-DK2/Examples/TIM/TIM_DMABurst' \
'STM32MP157C-DK2/Examples/UART/UART_TwoBoards_ComDMA' \
'STM32MP157C-DK2/Examples/UART/UART_TwoBoards_ComIT' \
'STM32MP157C-DK2/Examples/UART/UART_Receive_Transmit_Console' \
'STM32MP157C-DK2/Examples/WWDG/WWDG_Example' \
'STM32MP157C-DK2/Applications/FreeRTOS/FreeRTOS_ThreadCreation' \
'STM32MP157C-DK2/Applications/OpenAMP/OpenAMP_raw' \
'STM32MP157C-DK2/Applications/OpenAMP/OpenAMP_TTY_echo' \
'STM32MP157C-DK2/Applications/OpenAMP/OpenAMP_TTY_echo_wakeup' \
'STM32MP157C-DK2/Applications/CoproSync/CoproSync_ShutDown' \
'STM32MP157C-DK2/Demonstrations/AI_Character_Recognition' \
"

5.6.6. How to rebuild an example with OpenEmbedded[edit source]

If you need to provide a new software Linux image with a Linux file system updated with your changes, please follow the instructions below:

  • Make your changes in STM32MP1 Firmware source code (in <path_to_your_workspace>/sources/m4projects-stm32mp1/stm32cube_fw_mp1)
  • Go to the build folder
 cd <path_to_your_workspace>/build-<name_of_distro>
  • Clean the m4projects build folder
 bitbake m4projects-stm32mp1 -f -c cleanall 
  • Rebuild the recipe m4projects
 bitbake m4projects-stm32mp1 
  • Rebuild the image
 bitbake st-image-weston

5.6.7. How to download an image[edit source]

  • Please refer to Flashing_the_built_image to obtain all the information on how to Flash a new image on the STM32MP1 board

5.7. Logging in production mode[edit source]

On top of all the different tools supporting STM32CubeMP1 debugging, the different examples have integrated a way to log STM32CubeMP1 firmware visible from Linux (so only valid for production mode).
A resource table entry is dedicated for that, see: How_to_add_trace_for_the_log_buffer.
The principle:

  • "__LOG_TRACE_IO_" preprocessor flag needs to be defined
  • The logs done with log_info() or log_err() functions will be available in Linux sysfs file: "/sys/kernel/debug/remoteproc/remoteproc0/trace0"

These logs can be retrieved after a firmware crash: refer to How to retrieve Cortex-M4 logs after crash for more information.

6. References[edit source]