This repository has been archived on 2021-11-24. You can view files and clone it, but cannot push or open issues or pull requests.
fsfw_example_public/doc/README-stm32-rtems.md
2021-04-27 17:22:34 +02:00

147 lines
6.0 KiB
Markdown

# 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
}
```