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](https://docs.rtems.org/branches/master/user/bsps/bsps-arm.html#id25) 
   `arm/stm32h7` installed (`arm-rtems6`)
2. [MSYS2](https://www.msys2.org/) installed on Windows. Not required on Linux.
3. Recommended for application code development: 
   [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU 
   plugin
4. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging
5. STM32 USB drivers installed, separate steps for 
   [Windows](https://www.st.com/en/development-tools/stsw-link009.html) or 
   [Linux](https://fishpepper.de/2016/09/16/installing-using-st-link-v2-to-flash-stm32-on-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
   ```sh
   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
   ```

2. Set up submodules
   ```sh
   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.

   ```sh
   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:

   ```sh
   arm-rtems6-gcc --version
   ```
   
   Now we will create the build configuration for cross-compilation of an ARM target.
   On Linux, run the following command:
   
   ```sh
   cmake -G "Unix Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
   ```
   
   On Windows, use the following command:
   
   ```sh
   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
   
   ```sh
   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](https://docs.rtems.org/branches/master/user/start/index.html)
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](https://github.com/rmspacefish/rtems-tools). In any case, it is recommended
to use [this fork](https://github.com/rmspacefish/rtems/tree/mueller/master) 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](https://drive.google.com/drive/folders/15pO3FCUwceghrnYjmNlgC6K1Z8D_6iu2?usp=sharing)

## Setting up Eclipse for comfortable development

The separate [Eclipse README](README-eclipse#top) 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:

   ```sh
   $_CHIPNAME.cpu configure -event gdb-attach {
       halt
   }

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