STM32 Micrium ucOS-3 with SystemView

This project is the integration of Micrium's uC-OS-III Real-Time Operating System and SEGGER SystemView analyzer tool into STM32 microcontroller.

---

Board used in the project: Nucleo-F439ZI

Development Environment: STM32CubeIDE

---

Sources

Micrium Sources:

• uCOS-III Book: µC/OS-III: The Real-Time Kernel for the ST Microelectronics STM32
• uCOS-III Source Code:
  • uC-OS3
  • uC-CPU
  • uC-LIB
• Example Project for BSP code: Micrium_STM3240G-EVAL_OS3

SystemView Sources:

• SystemView Download: SystemView
• User Manual: SystemView User Manual (UM08027)
• SystemView Source Code: SystemView, Target Sources
• STLinkReflash : ST-LINK On-Board
  • Make sure you read the instructions carefully, have ST-LINK USB drivers and J-Link software package installed.

---

Integration Steps

The integration is committed into the repository step by step, with instructions and explanations given in each commit. While reading these steps, you can review the related commit alongside.

Step 1: Creating Project

Related commits: Default Project Created & Pinouts Cleared

• A new project is created in STM32 CubeIDE.
• Peripheral and clock configurations are made according to the application.

Step 2: Adding Micrium Source Code to Project

Related commit: Micrium Source Code Added

• The file structure followed is different than the recommended structure in the book.
• A folder named Micrium is created. Three new folders are created for each three source code repositories.
• Source codes from uC-CPU, uC-LIB and uC-OS3 are copied to their respective folders. uC-OS3 source code is inside the "Source" directory.
• There are CPU-specific port codes in each repositories. The appropriate port codes from each source are selected copied into their respective folders.
• There are configuration header file templates in each three repositories. These files are placed in folders called "Cfg" inside the source repositories. A seperate folder called "Cfg" is created inside the Micrium folder and these configuration files are copied into it.
• All of the new source code paths are added to source and include paths in project settings.

Step 3: Completing Micrium Integration

Related commit: Micrium Integration Completed

• First of all, the _dbg_uCOS-III.c file is deleted from Micrium/uC-OS3/Source
• Configurations are made in cpu_cfg and lib_cfg files, according to both user application and tracing needs. Timestamping has to be enabled for tracing.
  • CPU_CFG_NVIC_PRIO_BITS configuration constant must be configured according to the reference manual. It determines number of bits used by the microcontroller for interrupt priorities. It is defined in "Nested vectored interrupt controller" chapter in reference manual. For this project, it needs to be 4.
• Timebase source has to be changed to TIMx. In default, it is selected as SysTick when the project is first created. It is changed to TIM1 using System Core->SYS->Timebase Source path on CubeMX.

Step 3.1: Including BSP

• When timestamping and interrupt disabled time measurements are enabled, some user defined BSP code is needed. More specifically, CPU_TS_TmrInit() function.
• According to Micrium book, "It is a function that uC-CPU expects to have in order to initialize the timer that will be used for timestamps."
  • The official examples in the Weston-Embedded website and BSP codes in them are investigated.
  • In the STM3240G-EVAL example project, CPU_TS_TmrInit() function is found in cpu_bsp.c file. Entire file is copied into a new BSP folder.
  • BSP_CPU_ClkFreq() function is also needed. It is found in bsp.c file and copied into the cpu_bsp.c. It is a function that simply returns the SystemCoreClock value.
  • HAL library header is included in cpu_bsp.c
  • Source of example project: https://www.weston-embedded.com/micrium-examples/category/240-stm3240g-eval

Step 3.2: Including Micrium's Handlers

• Micrium's own PendSV and SysTick interrupt handlers need to be used.
  • The startup assembly file startup_stm32f4...s is modified and Micrium's handlers are added to the vector table:
  • All occurances of PendSV_Handler are replaced with OS_CPU_PendSVHandler.
  • All occurances of SysTick_Handler are replaced with OS_CPU_SysTickHandler.

Step 3.3: Testing the Integration

• An example LED blink program is implemented according to the multi-task application example from Getting Started section of the book.
• It is very important to initialize SysTick with "OS_CPU_SysTickInit" function call.
  • This function has to be called after the OSStart call, in other words, inside the starter task function.
  • The argument to the function is number of clock ticks between each OS tick interrupt. For example, in order to achieve a period of 1ms, clock frequency value is divided by 1000 and given as argument.
  • An alternative to this function is OS_CPU_SysTickInitFreq, where the CPU frequency is given as argument and the intended tick rate is specified via OS_CFG_TICK_RATE_HZ configuration constant in os_cfg_app.h file.
• The program is verified both by debugger and observing blinking LEDs.

Step 4: Adding SystemView Source Code

Related commit: SystemView Source Code Added

• SystemView source code is added to the according to the recommended structure in SystemView User Guide, "Getting started with SystemView on the target" chapter.
• Additionally, SEGGER/SEGGER_RTT_ASM_ARMv7M.S file is also included since the processor is ARMv7M based.

Step 5: Completing SystemView Integration

Related commit: Configuration and First SystemView Integration

• Configurations are made in Micrium's os_cfg.h configuration header file.
  • OS_CFG_DBG_EN and OS_CFG_TRACE_xxxx_EN constants are enabled.
• Configurations are made in SystemView's SEGGER_SYSVIEW_Config_uCOSIII.c configuration header file.
  • SYSVIEW_TIMESTAMP_FREQ constant is defined as CPU_TS_TmrFreqGet(&local_err). The local_err is created as a CPU_ERR variable.
  • SYSVIEW_CPU_FREQ constant is defined as SystemCoreClock. stm32f4xx.h header file is included to use it.
• The SEGGER_SYSVIEW.h is included in the main.c.
• SEGGER_SYSVIEW_Conf() and SEGGER_SYSVIEW_Start() functions are called just after the OSInit() call in main.c

Step 6: Testing the Integration

Related commit: Configuration and First SystemView Integration

• In order to use SystemView, the on-board ST-Link needs to be converted to J-Link using SEGGER's STLinkReflash utility. This program is also able to restore it back to ST-Link.
  • Before using the tool, the following page of ST-Link Reflash need to be read carefully: https://www.segger.com/products/debug-probes/j-link/models/other-j-links/st-link-on-board/
  • When prerequisites are met, ST-Link USB drivers and J-Link software package are installed, the program can be used.
  • Despite not being listed in Compatible Evaluation Boards, it is tested and worked without any issue on the Nucleo-F439ZI board.
• ST-Link is converted to J-Link using the STLinkReflash.
• SystemView is tested in real-time capture mode.
  • The application is started in debugger mode.
  • A breakpoint is put in the first statement after SEGGER_SYSVIEW_Start() function call and the program is resumed.
  • When program stops in the breakpoint, SystemView real-time tracing is started and then the program is resumed.

Step 7: Capturing ISRs

Related commit: Interrupt Record Functionality Added

• In order to record interrupts, SEGGER_SYSVIEW_RecordEnterISR() and SEGGER_SYSVIEW_RecordExitISR() calls need to be added to the beginning and ending of the interrupt handler function.
  • It is tested by creating a simple user button interrupt.