README correction

This commit is contained in:
Robin Müller 2021-07-15 16:57:51 +02:00
parent 6733b2eab7
commit a726fb7e5b
No known key found for this signature in database
GPG Key ID: 11D4952C8CCEF814

159
README.md
View File

@ -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:"<pathToToolchain>"
```
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 &rarr; C/C++ Build &rarr; 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
}
```