diff --git a/README.md b/README.md index d5967dd..d520e09 100644 --- a/README.md +++ b/README.md @@ -44,32 +44,32 @@ These files can be edited manually after `CMake` build generation. # FSFW demo with FreeRTOS OSAL on the STM32H743ZI -This demo can be run on a STM32H743ZI-Nucleo board with the FreeRTOS OSAL. +This demo can be run on a STM32H743ZI-Nucleo board with the RTEMS OSAL. -## General Information +## 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 long as OpenOCD integration is given. The example demo uses newlib nano (glibc). -Some system calls were overriden so the C and C++ stdio functions work. IO is sent via the HUART3, -so debug output can be read directly from the USB connection to the board. +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`) 1. [MinGW64](https://www.msys2.org/) or [Ninja Build](https://ninja-build.org/) installed on Windows. Not required on Linux. -2. [GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/) installed, recommended - to add binaries to system path. 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 -## Building the software with CMake +# Building the software with CMake On Windows, the following steps should be performed inside the MinGW64 console -after installing MSYS2 or inside another Unix shell like `git bash`. +after installing MSYS2. It is recommended to still use git for Windows for the git +related steps. 1. Clone this repository ```sh @@ -89,34 +89,33 @@ after installing MSYS2 or inside another Unix shell like `git bash`. mkdir build-Debug cd build-Debug ``` - -4. Ensure that the ARM compiler has been added to the path and can be called from - the command line. For example, the following command should work: + +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-none-eabi-gcc --version + arm-rtems6-gcc --version ``` Now we will create the build configuration for cross-compilation of an ARM target. - On Linux, the following build will create a debug build configuration with - the Unix Makefile generator. You can also specify `-G Ninja` to use Ninja instead - of Make. + On Linux, run the following command: ```sh - cmake .. + cmake -G "Unix Makefiles" -DOS_FSFW=rtems -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo .. ``` - On Windows, use the following command to build with the `MinGW Makefiles` build system + On Windows, use the following command: ```sh - cmake -G "MinGW Makefiles" .. + cmake -G "MinGW Makefiles" -DOS_FSFW=rtems -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 with the following command - + +5. Build the application + ```sh cmake --build . -j ``` @@ -129,95 +128,55 @@ after installing MSYS2 or inside another Unix shell like `git bash`. 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 +# Setting up the prerequisites -### Windows +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/nucleo-h743zi` 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. -It is recommended to install [MSYS2](https://www.msys2.org/) first. -Open MinGW64 and run the following commands to update it and install make and cmake -(replace x86_64 if compiling on different architecture): +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 +`arm/nucleo-h743zi` BSP. -```sh -pacman -Syu -``` +You can also download the pre-compiled toolchains from +[here](https://drive.google.com/drive/folders/15pO3FCUwceghrnYjmNlgC6K1Z8D_6iu2?usp=sharing) -```sh -pacman -S mingw-w64-x86_64-make mingw-w64-x86_64-cmake -``` +## Windows -Alternatively, you can install [Ninja Build](https://ninja-build.org/), but you need -to add the folder containing the `ninja.exe` executable to the system path so you -can run `ninja -v` from the command line. If you do this, you can also use -`git bash` or the Windows command lines with the CMake Ninja generator -to build the software. +You can install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html) -The code needs to be cross-compiled for the ARM target system and we will use the -[GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/). +## Linux -1. Install NodeJS LTS. Add nodejs folder (e.g. "C:\Program Files\nodejs\") - to system variables. Test by running `npm --version` in command line -2. Install [XPM](https://www.npmjs.com/package/xpm) - ```sh - npm install --global xpm - ``` - -3. Install gnu-arm Toolchain for Eclipse (version can be specified) - ```sh - xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@latest - ``` - - `xpm` will display where the package was installed. Search in that path for - the hidden `.content` folder, which will contain a `bin` folder and store - the full path to that `bin` folder for later. - - Install OpenOCD for STM32 debugging - ```sh - xpm install --global @xpack-dev-tools/openocd@latest - ``` - -4. If you want to build from the command line, you need to add the `arm-none-eabi-gcc` - binary location in the xPack folder to system variables. You can do this in a Unix - shell like `git bash` or `MinGW64` with the following command - - ```sh - export PATH=$PATH:"" - ``` - - You can also add these lines to a shell script like `path_setter.sh` and then source - the script with `. path_setter.sh` to do this conveniently. You can test whether - the path was set up properly by running `arm-none-eabi-gcc -v` - -5. Install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html) - -If you don't want to install nodejs you may go with the -[four-command manual installation](https://xpack.github.io/arm-none-eabi-gcc/install/#manual-install). - -### Linux - -Install the [GNU ARM toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/) -like explained above. - -To install general buildtools for the linux binary, run: -```sh -sudo apt-get install build-essential -``` - -Install the [USB drivers](https://github.com/stlink-org/stlink) on Linux. -On Ubuntu, you can run the following command to install it: +You can install the STM32 USB drivers on Ubuntu with the following command ```sh sudo apt-get install stlink-tools ``` -## Setting up Eclipse for OpenOCD debugging +# 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 +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. -## Troubleshooting +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. -### OpenOCD errors +# 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: @@ -228,15 +187,15 @@ switching between FreeRTOS and RTEMS. You can try the following steps: 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: Add the following lines to the `stm32h7x.cfg` file located inside the OpenOCD folder - inside the `scripts/target` folder: +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 { + $_CHIPNAME.cpu0 configure -event gdb-attach { halt } - $_CHIPNAME.cpu configure -event gdb-attach { + $_CHIPNAME.cpu0 configure -event gdb-attach { reset init } ```