Using I-CUBE-embOS with STM32CubeMX

embOS was granted the MadeForSTM32 label. As part of that, SEGGER offers the I-CUBE-embOS expansion for STM32CubeMX that allows users to generate and configure embOS projects in STM32CubeMX for use with virtually all STM32 devices and various IDEs. This article provides further information on that expansion and its usage.

For using a regular embOS shipment with STM32CubeMX (i.e. not using the expansion package), please refer to Using embOS with STM32CubeMX.

MadeForSTM32

MadeForSTM32 is a quality label delivered by ST and granted after an extended evaluation process. It helps engineers identify software solutions with the highest level of integration and quality for the STM32 microcontrollers' ecosystem.

embOS was one of the first solutions to receive the MadeForSTM32 (v1) label in an advanced collaboration of SEGGER and ST Microelectronics and has since been certified to MadeForSTM32 (v2) as well. As a result, SEGGER has published the official I-CUBE-embOS expansion for STM32CubeMX, which may be used to generate ready-to-go embOS projects for virtually all Cortex-M devices and various IDEs.

For more information on MadeForSTM32, please visit SEGGER.com.

embOS expansion for STM32CubeMX

The I-CUBE-embOS expansion for STM32CubeMX contains the embOS CMSIS-Pack, which may also be used independently of STM32CubeMX.
This article focuses on its usage in STM32CubeMX. For its independent usage in various IDEs, please refer to Using embOS in CMSIS-Pack projects.

Download

The I-CUBE-embOS expansion for STM32CubeMX may be obtained from SEGGER.com.

After download, the *.pack-file may be accessed or extracted like a *.zip-file and contains the following files and folders:

File / Folder	Description
Middlewares\	Contains the embOS documentation, pre-build libraries, include files and target source files for use with GNU, IAR and Keil toolchains
Projects\	Contains a pre-generated STM32CubeMX example project for the STM3240G-Eval board each for IAR Embedded Workbench, arm Keil µVision, and STM32CubeIDE
STM32CubeMX\	Contains additional source code templates for code generation using STM32CubeMX
License.txt	The license agreement under which this software pack is provided
ReadMe.txt	Trouble-shooting guide for this software pack (also available in #Trouble-shooting)
SEGGER.I-CUBE-embOS.pdsc	The Pack description file for this software pack

Installation

The I-CUBE-embOS expansion for STM32CubeMX may be used as-is: it does not need to be extracted before installing it in STM32CubeMX.

To install it, the following steps should be taken:

1. Upon starting STM32CubeMX, select Help -> Manage embedded software packages
2. Select From Local ... and specify the downloaded SEGGER.I-CUBE-embOS.1.2.0.pack (installs V1.2.0 of the pack, file name may differ for later versions)

This will extract the pack to your local STM32Cube repository and make it available in the Packages Manager as shown below:

Usage

After sucessfull installation, the I-CUBE-embOS expansion for STM32CubeMX can be used to generate various projects with embOS.
Here, a project for the STM3240G-Eval board and the IAR Embedded Workbench is created, but the same steps should be applied when creating a project for any other evaluation board or device and/or any other IDE.

Creating the basic project

Start STM32CubeMX and create a project for the desired target hardware. After the project was initialized, feel free to add clock configurations, GPIO settings and further settings as needed. The result should resemble the screenshot below:

In case the generated project is pre-configured for using any other RTOS than embOS, that RTOS must be disabled via Middleware and Software packs -> <RTOS Name> -> Interface.

Adding embOS to the project

Now, select Software Packs -> Select components and add embOS to the project. To do so, select the required components:

• SEGGER.I-CUBE.embOS
  • RTOS embOS
    1. embOS API configuration
       • Native (allows usage of embOS native API only)
       • CMSIS-RTOS (allows usage of embOS native API and CMSIS-RTOS (v1) API)
       • CMSIS-RTOS2 (allows usage of embOS native API and CMSIS-RTOS (v2) API)
    2. embOS kernel configuration
       • Debug and Trace
       • Debug and Profiling
       • Debug
       • Stack check and Profiling
       • Stack check
       • Release
       • Extreme Release

An optional embOS sample application may be added as well. However, we do not recommend adding one of these with STM32CubeMX, for this will result in duplicate implementations of main(). Instead, we will customize a sample application in STM32CubeMX later on.

For example, for a Debug and Profiling configuration using the native embOS API, the Component Selector window would look as shown below:

Feel free to add further components as desired.
After closing the component selector, the selected embOS components need to be activated in the Software Packs -> Mode view:

embOS for Cortex-M uses the SysTick as a hardware timer for the system tick. Since HAL also uses the SysTick per default we need to change the hardware timer for the HAL. This is done by changing the Timebase Source in the SystemCore -> SYS Mode and Configuration view to any other timer than the SysTick.

Customizing the sample application

Now, Software Packs -> Configuration may be used to customize the generation of main.c (i.e. the sample application) for demonstrating embOS' usage (a real-world application would need to modify the generated source code manually in order to fully customize the application, which is not possible in STM32CubeMX itself).

In this example, we will implement one task body and create two extended tasks executing that body, and also implement and create one software timer. Hence, the Tasks tab would look like this:

The Software timer tab would like as follows:

Feel free to add further embOS objects to your application as desired.

Generating and executing the project

The STM32CubeMX configuration may now be used to create a project for the desired IDE. In this example, we create a project for IAR Embedded Workbench. After creation, open the project which should resemble the following structure:

Subsequently, the project may be compiled without warning or error and executed in hardware.
Feel free to modify it and add your own application to the project.

Trouble-shooting

Linker Symbols with arm Keil µVision

When creating projects for arm Keil µVision, manual modification may be required to the used start-up file (e.g. startup_stm32f407xx.s).

If the linker complains about the undefined symbol Stack_Mem, the Stack_Mem symbol needs to be exported by the start-up file (e.g. startup_stm32f407xx.s). Please add

       EXPORT  Stack_Mem

to the start-up file.

Alternatively, if another symbol pointing to the end of the stack (lowest address of the stack) is exported, OS_InitSysStackInfo.c can be modified to use this symbol instead of Stack_Mem.

If the linker complains about the undefined symbol __initial_sp, the __initial_sp symbol needs to be exported by the start-up file (e.g. startup_stm32f407xx.s). Please add

       EXPORT  __initial_sp

to the start-up file.

Please note, that there might be conflicts with the stack/heap set up methods and ARM compiler V6 when __initial_sp is exported and MicroLIB is not used. In this case, and if the start-up file supports the use of MicroLIB, MicroLIB can be enabled instead of exporting __initial_sp (Options for Target -> Target -> Code Generation -> Use MicroLIB).

Alternatively, if another symbol pointing to the beginning of the stack (highest address of the stack) is exported, OS_InitSysStackInfo.c can be modified to use this symbol instead of __initial_sp.

Linker Symbols with GNU toolchains

When creating projects for GNU toolchains, manual modification may be required to the used linker file (e.g. STM32F407IGHX_FLASH.ld):
If the linker cannot find __stack_start__ and/or __stack_end__, these symbols are not defined in the linker file. To resolve this, please replace

       . = . + _Min_Stack_Size;

by

       __stack_start__ = .;
       . = . + _Min_Stack_Size;
       __stack_end__ = .;

in the linker file.

Also, please ensure the reset value of the system stack pointer (contained in the respective project's vector table at offset 0x0) matches the value of __stack_end__.

OS_Error() called with error code OS_ERR_INIT_NOT_CALLED

When debugging an application that was generated using the above steps, embOS debug configurations may detect an Runtime application error and call OS_Error() with error code OS_ERR_INIT_NOT_CALLED .
This may happen when the STM32 HAL initializes the system tick early in the application and the system tick interrupt gets executed before OS_Init() was executed by the application. This does not happen in typical applications, but may occur e.g. when extensive hardware initialization is performed between configuration of the system tick and the call to OS_Init(). To resolve this, ensure OS_Init() is called before HAL_Init() and/or SystemClock_Config() (typically called from main()).