fsfw_example_public/doc/README-stm32-rtems.md

FSFW demo with RTEMS OSAL on the STM32H743ZI

This demo can be run on a STM32H743ZI-Nucleo board with the RTEMS OSAL. This example is still a work-in-progress.

General information

The board is flashed and debugged with OpenOCD and this README specifies on how to make this work with the Eclipse IDE. Other IDEs or the command line can be used as well as long as OpenOCD integration is given. Debug otuput can be read directly from the USB connection to the board.

Prerequisite

1. RTEMS BSP arm/stm32h7 installed (arm-rtems6)
2. MSYS2 installed on Windows. Not required on Linux.
3. Recommended for application code development: Eclipse for C/C++ installed with the Eclipse MCU plugin
4. OpenOCD installed for Eclipse debugging
5. STM32 USB drivers installed, separate steps for Windows or Linux

Building the software with CMake

On Windows, the following steps should be performed inside the MinGW64 console after installing MSYS2. It is recommended to still use git for Windows for the git related steps.

1. Clone this repository

   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
   

2. Set up submodules

   git submodule init
   git submodule update
   

3. Navigate into the cloned repository and create a folder for the build. We will create a Debug build folder.

   mkdir Debug-STM32-RTEMS
   cd Debug-STM32-RTEMS
   

4. Ensure that the RTEMS ARM compiler has been added to the path and can be called from the command line. For example, the following command should work:

   arm-rtems6-gcc --version
   

   Now we will create the build configuration for cross-compilation of an ARM target. On Linux, run the following command:

   cmake -G "Unix Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
   

   On Windows, use the following command:

   cmake -G "MinGW Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
   

   The build configuration can also be performed with the shell scripts located inside cmake/scripts/RTEMS or the Python helper script cmake_build_config.py inside cmake/scripts.

5. Build the application

   cmake --build . -j
   

   The application will be located inside the Debug folder and has been compiled for the flash memory.

6. You can test the application by first connecting the STM32H743ZI-Nucleo via USB. The device should now show up in the list of connected devices (make sure the USB drivers are installed as well). Drag and drop the binary file into the connected device to flash it. The debug output is also sent via the connected USB port and a blink pattern (1 second interval) can be used to verify the software is running properly.

Setting up the prerequisites

Building a software for RTEMS generally requires building a cross-compiler toolchain for the target architecture first and then building a board or chip specific BSP. The RTEMS QuickStart Guide specifies the general steps required to build a BSP. The following steps will show how to build the arm/stm32h7 BSP required for the STM32H743ZI-Nucleo board. It is recommended to build the BSP on Linux because the build process in Windows has proven problematic numerous times. On Windows, it is recommended to download a pre-compiled tool suite or build cross-compile the toolchain for Windows on a Linux system. The BSP build process with waf should work on both OSes without issues.

For Linux, it is recommended you clone and follow the steps specified in this respository. In any case, it is recommended to use this fork to build the BSP from the RTEMS sources because it contains important fixes for the relatively new stm32h7 BSP.

You can also download the pre-compiled toolchains from here

Setting up Eclipse for comfortable development

The separate Eclipse README specifies how to set up Eclipse. The STM32 configuration uses the xPacks OpenOCD and the xPacks ARM Toolchain, so those should be installed as well. OpenOCD should be configured correctly in the STM32 launch configurations.

It is recommended to use the given project files which include a RTEMS configuration which only requires a few steps to work properly. When using the project files, go to the project properties → C/C++ Build → Build Variables and adapt the build variable RTEMS_PREFIX to point to your RTEMS prefix location, for example $HOME/RTEMS/rtems-tools/rtems/6. After that, Eclipse should be able to autodetermine the BSP specific include paths.

Troubleshooting

OpenOCD errors

If you get the following error in OpenOCD: "Error: auto_probe failed", this could be related from switching between FreeRTOS and RTEMS. You can try the following steps:

1. First way: Flash the binary manually by drag & droping the binary into the USB drive manually once

2. Second way: Add -c "gdb_memory_map disable" to the OpenOCD arguments (in Eclipse) and run once. Debugging might not be possible, so remove it for subsequent runs.

3. Third way (most reliable): Add the following lines to the stm32h7x.cfg file located inside the OpenOCD folder inside the scripts/target folder:

   $_CHIPNAME.cpu configure -event gdb-attach {
       halt
   }
   
   $_CHIPNAME.cpu configure -event gdb-attach {
       reset init
   }