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):
- STM32CubeMP1 Firmware Package embedded software libraries, including:
- 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
- STM32CubeMX tool, including :
- 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).
3. Software architecture overview[edit source]
The STM32CubeMP1 Package is based on the STM32Cube MCU package and 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.
The figure below gives an overview of the STM32CubeMP1 architecture.
4. STM32CubeMP1 Package content[edit source]
STM32CubeMP1 Package offers a highly portable Hardware Abstraction Layer (HAL), built around a generic and modular architecture.
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.
4.2. Drivers[edit source]
The Drivers folder contains all the STM32Cube Drivers, including BSP and HAL drivers
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
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 │ └── STM32CubeIDE 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) :
- Examples, applications and demonstrations for STM32MP157C-EV1
├── STM32MP157C-EV1 │ ├── Applications │ │ ├── CoproSync │ │ ├── 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 │ ├── Applications │ │ ├── CoproSync │ │ ├── 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. For more details, refer to the following articles:
- Please read the article Which Package better suits your needs for further information on all packages.
- Please select your board Category:STM32 MPU boards to get the right package materials (software, hardware, documentation, and so on)
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 resources 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
- Engineering boot mode is used specifically for firmware testing directly on the coprocessor, this means:
- all resources 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)
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):
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 firmware)
5.4.1. Prerequisites[edit source]
- Please refer to the Starter Package for STM32MP15 Eval Board or Starter Package for STM32MP15 Discovery Board for all the information describing how to install the Starter Package
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 them.
This means that you need to select, by example, 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
[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
- This loads and starts the firmware using the Linux Remote Processor component in Cortex-M4
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 resource settings used by the example.
5.5. Developer Package for STM32CubeMP1[edit source]
Developer Package provides all the STM32Cube MPU source code and tools.
5.5.1. Prerequisites[edit source]
- Please refer to the Installing the STM32CubeMP1 Package to obtain and install the source code
- Please refer to the new preferred IDE: STM32CubeIDE
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:
- Click on following button to build the example:
5.5.2.2. How to download and run an example[edit source]
- Open the Serial Console to check the IP address of the board:
- Open the Debug Configurations panel:
- Configure the Main panel to add the firmware binary:
- Configure the Startup' panel to load and run the Firmware in the target:
5.5.2.3. How to start/stop an example[edit source]
- Locate path where the firmware has been loaded
- Use a script to start/stop the firmware
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 generates a full distribution based on Linux OS. All example binaries (or firmware) are integrated in the Linux file system.
5.6.1. Prerequisites[edit source]
Please refer to
- OpenSTLinux Distribution Package for further information about the OpenSTLinux distribution.
- Installing the OpenSTLinux distribution for further information on how to install and initialize the OpenSTLinux environment
- STM32MP15 OpenSTLinux layer for further information about the dedicated M4 project recipe (named m4projects-stm32mp1)
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.
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 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 (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
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]
- Refer to Flashing_the_built_image to obtain all 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 in 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]
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.