Merge pull request 'BBB x-compile guide added' (#7) from mueller/bbb-guide into master

Reviewed-on: #7

README.md

@@ -27,6 +27,7 @@ the TMTC capabilities of the FSFW (currently, using the ECSS PUS packet standard
 [Getting started with the Host OSAL](doc/README-host.md#top)<br>
 [Getting started with the FreeRTOS OSAL on a STM32](doc/README-stm32-freertos.md#top)<br>
 [Getting started with the Raspberry Pi](doc/README-rpi.md#top)<br>
+[Getting started with the Beagle Bone Black](doc/README-bbb.md#top)<br>
 [Getting started with the RTEMS OSAL on a STM32](doc/README-stm32-rtems.md#top)<br>
 [Getting started with Eclipse for C/C++](doc/README-eclipse.md#top)<br>
 [Getting started with CMake](doc/README-cmake.md#top)<br>

cmake/BBBCrossCompileConfig.cmake

@@ -0,0 +1,98 @@
+# BBB_ROOTFS should point to the local directory which contains all the 
+# libraries and includes from the target raspi.
+# The following command can be used to do this, replace <ip-address> and the
+# local <rootfs-path> accordingly:
+# rsync -vR --progress -rl --delete-after --safe-links pi@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
+# RASPBIAN_ROOTFS needs to be passed to the CMake command or defined in the
+# application CMakeLists.txt before loading the toolchain file.
+
+# CROSS_COMPILE also needs to be set accordingly or passed to the CMake command
+
+if(NOT DEFINED ENV{BBB_ROOTFS})
+	message(FATAL_ERROR 
+		"Define the BBB_ROOTFS variable to point to the Beagle Bone Black rootfs."
+	)
+else()
+	set(SYSROOT_PATH "$ENV{BBB_ROOTFS}")
+	message(STATUS "Beagle Bone Black sysroot: ${SYSROOT_PATH}")
+endif()
+
+if(NOT DEFINED ENV{CROSS_COMPILE})
+	set(CROSS_COMPILE "arm-linux-gnueabihf")
+	message(STATUS 
+		"No CROSS_COMPILE environmental variable set, using default ARM linux "
+		"cross compiler name ${CROSS_COMPILE}"
+	)
+else()
+	set(CROSS_COMPILE "$ENV{CROSS_COMPILE}")
+	message(STATUS 
+		"Using environmental variable CROSS_COMPILE as cross-compiler: "
+		"$ENV{CROSS_COMPILE}"
+	)
+endif()
+
+message(STATUS "Using sysroot path: ${SYSROOT_PATH}")
+
+set(CROSS_COMPILE_CC "${CROSS_COMPILE}-gcc")
+set(CROSS_COMPILE_CXX "${CROSS_COMPILE}-g++")
+set(CROSS_COMPILE_LD "${CROSS_COMPILE}-ld")
+set(CROSS_COMPILE_AR "${CROSS_COMPILE}-ar")
+set(CROSS_COMPILE_RANLIB "${CROSS_COMPILE}-ranlib")
+set(CROSS_COMPILE_STRIP "${CROSS_COMPILE}-strip")
+set(CROSS_COMPILE_NM "${CROSS_COMPILE}-nm")
+set(CROSS_COMPILE_OBJCOPY "${CROSS_COMPILE}-objcopy")
+set(CROSS_COMPILE_SIZE "${CROSS_COMPILE}-size")
+
+# At the very least, cross compile gcc and g++ have to be set!
+find_program (CROSS_COMPILE_CC_FOUND ${CROSS_COMPILE_CC} REQUIRED)
+find_program (CROSS_COMPILE_CXX_FOUND ${CROSS_COMPILE_CXX} REQUIRED)
+
+set(CMAKE_CROSSCOMPILING TRUE)
+set(CMAKE_SYSROOT "${SYSROOT_PATH}")
+
+# Define name of the target system
+set(CMAKE_SYSTEM_NAME "Linux")
+set(CMAKE_SYSTEM_PROCESSOR "arm")
+
+# Define the compiler
+set(CMAKE_C_COMPILER ${CROSS_COMPILE_CC})
+set(CMAKE_CXX_COMPILER ${CROSS_COMPILE_CXX})
+
+# List of library dirs where LD has to look. Pass them directly through gcc. 
+# LD_LIBRARY_PATH is not evaluated by arm-*-ld
+set(LIB_DIRS 
+	"${SYSROOT_PATH}/lib/${CROSS_COMPILE}"
+	"${SYSROOT_PATH}/usr/local/lib"
+	"${SYSROOT_PATH}/usr/lib/${CROSS_COMPILE}"
+	"${SYSROOT_PATH}/usr/lib"
+)
+# You can additionally check the linker paths if you add the 
+# flags ' -Xlinker --verbose'
+set(COMMON_FLAGS "-I${SYSROOT_PATH}/usr/include")
+foreach(LIB ${LIB_DIRS})
+	set(COMMON_FLAGS "${COMMON_FLAGS} -L${LIB} -Wl,-rpath-link,${LIB}")
+endforeach()
+
+set(CMAKE_PREFIX_PATH 
+	"${CMAKE_PREFIX_PATH}"
+	"${SYSROOT_PATH}/usr/lib/${CROSS_COMPILE}"
+)
+
+set(CMAKE_C_FLAGS 
+	"-march=armv7-a -mtune=cortex-a8 -mfpu=neon -mfloat-abi=hard ${COMMON_FLAGS}" 
+	CACHE STRING "Flags for Beagle Bone Black"
+)
+set(CMAKE_CXX_FLAGS "${CMAKE_C_FLAGS}" 
+	CACHE STRING "Flags for Beagle Bone Black"
+)
+
+set(CMAKE_FIND_ROOT_PATH 
+	"${CMAKE_INSTALL_PREFIX};${CMAKE_PREFIX_PATH};${CMAKE_SYSROOT}"
+)
+
+# search for programs in the build host directories
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+# for libraries and headers in the target directories
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

cmake/PreProjectConfig.cmake

@@ -110,15 +110,19 @@ elseif(${OS_FSFW} STREQUAL linux AND TGT_BSP)
 				"$ENV{RASPBERRY_VERSION}"
 			)
 		endif()
-
             if(LINUX_CROSS_COMPILE)
                 set(CMAKE_TOOLCHAIN_FILE
                     "${CMAKE_SCRIPT_PATH}/RPiCrossCompileConfig.cmake"
                     PARENT_SCOPE
                 )
-	    endif()
+            endif()
         elseif(${TGT_BSP} MATCHES "arm/beagleboneblack")
-
+            if(LINUX_CROSS_COMPILE)
+                set(CMAKE_TOOLCHAIN_FILE
+                    "${CMAKE_SCRIPT_PATH}/BBBCrossCompileConfig.cmake"
+                    PARENT_SCOPE
+                )
+            endif()
 	else()
 		message(WARNING "Target BSP (TGT_BSP) ${TGT_BSP} unknown!")
 	endif()

cmake/scripts/BeagleBoneBlack/crosscompile/bbb_path_helper.sh

@@ -0,0 +1,3 @@
+export PATH=$PATH:"$HOME/beaglebone/<cross_compiler_path>/bin"
+export CROSS_COMPILE="arm-linux-gnueabihf"
+export BBB_ROOTFS="${HOME}/raspberrypi/rootfs"

cmake/scripts/BeagleBoneBlack/crosscompile/create_cmake_debug_cfg.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+counter=0
+while [ ${counter} -lt 5 ]
+do
+	cd ..
+	if [ -f "cmake_build_config.py" ];then
+		break
+	fi
+	counter=$((counter=counter + 1))
+done
+
+if [ "${counter}" -ge 5 ];then
+	echo "cmake_build_config.py not found in upper directories!"
+	exit 1
+fi
+
+os_fsfw="linux"
+tgt_bsp="arm/beagleboneblack"
+build_generator=""
+builddir="build-Debug-BBB"
+defines="LINUX_CROSS_COMPILE=ON"
+if [ "${OS}" = "Windows_NT" ]; then
+	build_generator="MinGW Makefiles"
+# Could be other OS but this works for now.
+else
+	build_generator="Unix Makefiles"
+fi
+
+python3 cmake_build_config.py -o "${os_fsfw}" -g "${build_generator}" -b "debug" -t "${tgt_bsp}" \
+		-l "${builddir}" -d "${defines}"

cmake/scripts/BeagleBoneBlack/crosscompile/create_cmake_release_cfg.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+counter=0
+while [ ${counter} -lt 5 ]
+do
+	cd ..
+	if [ -f "cmake_build_config.py" ];then
+		break
+	fi
+	counter=$((counter=counter + 1))
+done
+
+if [ "${counter}" -ge 5 ];then
+	echo "cmake_build_config.py not found in upper directories!"
+	exit 1
+fi
+
+os_fsfw="linux"
+tgt_bsp="arm/beagleboneblack"
+build_generator=""
+builddir="build-Release-BBB"
+defines="LINUX_CROSS_COMPILE=ON"
+if [ "${OS}" = "Windows_NT" ]; then
+	build_generator="MinGW Makefiles"
+# Could be other OS but this works for now.
+else
+	build_generator="Unix Makefiles"
+fi
+
+python3 cmake_build_config.py -o "${os_fsfw}" -g "${build_generator}" -b "debug" -t "${tgt_bsp}" \
+		-l "${builddir}" -d "${defines}"

cmake/scripts/BeagleBoneBlack/crosscompile/create_cmake_relwithdeb_cfg.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+counter=0
+while [ ${counter} -lt 5 ]
+do
+	cd ..
+	if [ -f "cmake_build_config.py" ];then
+		break
+	fi
+	counter=$((counter=counter + 1))
+done
+
+if [ "${counter}" -ge 5 ];then
+	echo "cmake_build_config.py not found in upper directories!"
+	exit 1
+fi
+
+os_fsfw="linux"
+tgt_bsp="arm/beagleboneblack"
+build_generator=""
+builddir="build-Release-BBB"
+defines="LINUX_CROSS_COMPILE=ON"
+if [ "${OS}" = "Windows_NT" ]; then
+	build_generator="MinGW Makefiles"
+# Could be other OS but this works for now.
+else
+	build_generator="Unix Makefiles"
+fi
+
+python3 cmake_build_config.py -o "${os_fsfw}" -g "${build_generator}" -b "debug" -t "${tgt_bsp}" \
+		-l "${builddir}" -d "${defines}"

doc/README-bbb.md

@@ -0,0 +1,411 @@
+<img align="center" src="./images/bbb/beagleboard-logo.png" width="30%">
+
+<sub><sup>Image taken from [Beagle Board website](https://beagleboard.org/logo) and used in
+accordance with their trademark rules.</sup></sub>
+
+# Getting started on the Beagle Bone Black
+
+The FSFW can be run on a Beagle Bone Black with the Linux OSAL, using
+an ARM linux (cross) compiler. Instructions will be provided on how to do this.
+
+## General Information
+
+The following instructions will show how to build the example on the Beagle Bone Black directly.
+It will also show how to cross-compile on a host machine and mirror the Beagle Bone sysroot folder
+on the host machine so that the same libraries and headers used on the BBB are used
+for the cross-compilation process.
+
+Some Eclipse project files were provided as well to help with setting up the indexer in Eclipse
+more quickly.
+
+## Prerequisites for direct compilation and cross-compiling
+
+1. SSH connection to the Beagle Bone Black working 
+2. Beagle Bone Black linux environment set up properly
+3. `CMake` installed
+
+## Setting up general prerequisites for Linux systems
+
+1. Install CMake and rsync
+
+    ```sh
+    sudo apt-get install cmake rsync
+    ```
+
+2. Configure the Beagle Bone Black Linux environment. The last section of the
+   [Linux README](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and
+   is also applicable to the Beagle Bone Black. SSH into the BBB and
+   follow the instructions in that section.
+
+3. Install the `gpiod` library
+
+   ```sh
+   sudo apt-get install gpiod libgpiod-dev
+   ```
+
+## Getting started on the Beagle Bone Black
+
+Make sure to follow the steps above. Now you should be able to build the software on 
+the Beagle Bone Black. A ssh connection to the Raspberry Pi is assumed here
+
+You can build the software with the following commands
+
+```sh 
+mkdir build-Debug-BBB
+cd build-Debug-BBB
+cmake -DOS_FSFW=linux -DTGT_BSP=arm/beagleboneblack -DLINUX_CROSS_COMPILE=OFF -DCMAKE_BUILD_TYPE=Debug ..
+cmake --build . -j2
+```
+
+## Prerequisites for cross-compiling
+
+These prerequisites are valid for Linux as well as Windows hosts.
+
+1. ARM Linux cross compiler installed
+2. Beagle Bone Black sysroot folder mirrored on the host machine, using `rsync`
+3. gdb-multiarch installed on host for remote debugging or `tcf-agent` running on the BBB
+
+## Cross-Compiling on a Linux Host
+
+### Setting up prerequisites for cross-compiling
+
+1. Install `CMake` and `rsync`
+
+   ```
+   sudo apt-get install cmake rsync
+   ```
+
+2. Configure the Beagle Bone Black linux environment. The last section of the
+   [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment
+   for the FSFW and isalso applicable to the Raspberry Pi. SSH into the
+   Beagle Bone Black and follow the instructions in that section.
+
+3. Install the correct [ARM Linux cross-compile toolchain](https://releases.linaro.org/components/toolchain/binaries/latest-7/arm-linux-gnueabihf/).
+   provided by Linaro.
+
+   Test the toolchain by running:
+
+   ```sh
+   arm-linux-gnueabihf-gcc --version
+   ```
+
+4. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
+   the BBB is working without issues. Then perform the following steps
+
+   ```sh
+   cd $HOME
+   mkdir beaglebone
+   cd beaglebone
+   mkdir rootfs
+   cd rootfs
+   pwd
+   ```
+
+   Store the result of `pwd`, it is going to be used by `rsync` later.
+
+   Now use `rsync` to clone the BBB sysroot to the local host machine.
+   You can replace `<ip-address>` with `beaglebone.local` to use DNS.
+   Use the rootfs location stored from the previous steps as `<rootfs-path>`.
+
+   ```sh
+   rsync -avHAXR --delete-after --info=progress2 --numeric-ids <user_name>@<ip_address>:/{usr,lib} <rootfs_path>
+   ```
+
+   On Linux, it is recommended to repair some symlinks which can be problematic:
+   Navigate to the folder containing the symlinks first:
+
+   ```sh
+   cd <rootfs_path>/usr/lib/arm-linux-gnueabihf
+   ```
+
+   You can now use
+
+   ```sh
+   readlink libpthread.so
+   ```
+
+   which will show an absolute location of a shared library the symlinks points to. This location
+   needs to be converted into a relative path.
+
+   Run the following command to create a relative symlinks instead of an absolute ones. The pointed
+   to location might change to check it with `readlink` first before removing the symlinks:
+
+   ```sh
+   rm libpthread.so
+   rm librt.so
+   ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so
+   ln -s ../../../lib/arm-linux-gnueabihf/librt.so.1 librt.so
+   ```
+
+   For more information on issues which can occur when cloning the root filesystem,
+   see the [troubleshooting](#troubleshooting) section.
+
+5. It is recommended to install `gdb-multiarch`. This tool will allow remote debugging on the host
+   computer. This is not required if the `tcf-agent` is used.
+
+   ```sh
+   sudo apt-get install multiarch
+   ```
+
+6. Perform the steps [in the following chapter](#cross-test) to build the
+   software for the BBB and test it.
+   
+## Cross-Compiling on a Windows Host
+
+### Additional Prerequites
+
+1. [MSYS2](https://www.msys2.org/) installed. All command line steps shown here
+   were performed in the MSYS2 MinGW64 shell (not the default MSYS2, use MinGW64!).
+   Replace `<UserName>` with respectively. It is recommended to set up
+   aliases in the `.bashrc` file to allow quick navigation to the `fsfw_example`
+   repository and to run `git config --global core.autocrlf true` for git in
+   MinGW64.
+
+### Setting up prerequisites for Windows
+
+1. Install CMake and rsync in MinGW64 after installing MSYS2
+
+   ```
+   pacman -S mingw-w64-x86_64-cmake rsync
+   ```
+   
+2. Configure the Beagle Bone Black linux environment. The last section of the 
+   [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment 
+   for the FSFW and isalso applicable to the Raspberry Pi. SSH into the 
+   Beagle Bone Black and follow the instructions in that section.
+
+3. Install the correct [ARM Linux cross-compile toolchain](https://releases.linaro.org/components/toolchain/binaries/latest-7/arm-linux-gnueabihf/).
+   provided by Linaro.
+
+   Test the toolchain by running:
+
+   ```sh
+   arm-linux-gnueabihf-gcc --version
+   ``` 
+
+4. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
+   the BBB is working without issues. Then perform the following steps
+
+   ```sh
+   cd /c/Users/<UserName>
+   mkdir beaglebone
+   cd beaglebone
+   mkdir rootfs
+   cd rootfs
+   pwd
+   ```
+
+   Store the result of `pwd`, it is going to be used by `rsync` later.
+
+   Now use rsync to clone the BBB sysroot to the local host machine.
+   You can replace `<ip-address>` with `beaglebone.local` to use DNS.
+   Use the rootfs location stored from the previous steps as `<rootfs-path>`.
+
+   ```sh
+   rsync -avHAXR --numeric-ids --info=progress2 <username>@<ip-address>:/{lib,usr} <rootfs-path>
+   ```
+   
+   Please note that `rsync` sometimes does not copy shared libraries or symlinks properly,
+   which might result in errors when cross-compiling and cross-linking. It is recommended to run
+   the following commands in addition to the `rsync` command on Windows:
+   
+   ```sh
+   scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/{libc.so.6,ld-linux-armhf.so.3,libm.so.6} <rootfs_path>/lib/arm-linux-gnueabihf
+   scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/{libpthread.so,libc.so,librt.so} <rootfs_path>/usr/lib/arm-linux-gnueabihf
+   ```
+   
+   For more information on issues which can occur when cloning the root filesystem,
+   see the [troubleshooting](#troubleshooting) section.
+
+5. It is recommended to install `gdb-multiarch`. This tool will allow remote debugging on the host 
+   computer. Replace `x86_64` with the correct processor architecture for other architectures.
+   This is not required if the `tcf-agent` is used.
+ 
+   ```sh
+   pacman -S mingw-w64-x86_64-gdb-multiarch
+   ```
+
+6. Perform the steps [in the following chapter](#cross-test) to build the
+   software for the BBB and test it.
+
+## <a id="cross-test"></a> Testing the cross-compilation
+
+It is recommended to set the following environmental variables for the CMake build:
+   - `CROSS_COMPILE`: Explicitely specify the name of the cross compiler 
+   - `BBB_ROOTFS`: Explicitely set the path to the local BBB rootfs
+
+For example with the following commands
+
+```sh
+export CROSS_COMPILE="arm-linux-gnueabihf"
+```
+
+It is recommended to test whether the environmental variables were set correctly,
+for example by running
+
+```sh
+echo $BBB_ROOTFS
+```
+
+These variables can either be set every time before a debugging session to
+keep the environment clean (should be done before starting Eclipse)
+or permanently by adding the `export` commands to system files.
+
+A helper script has been provided in `cmake/scripts/BBB` to perform
+setting up the environment. The scripts need to be `source`d instead of 
+being run like regular shell scripts. 
+
+You can also set up the environmental variables permanently by adding the 
+export commands to the `.profile` or `.bashrc` file in the `$HOME` folder.
+On Windows, MinGW64 was used to set up the build system, so you can use the
+MinGW64 `.bashrc` file to do this. If you are using Eclipse to build 
+the software, Eclipse will have the system variables from Windows,
+so it is recommended to either permanently set the three environmental
+variables in the Windows system environmental variables or add them in
+Eclipse. See the [Eclipse README](README-eclipse.md#top) for more information.
+
+Now we can test whether everything was set up properly by compiling the example
+and running it on the BBB via command line. Navigate into the `fsfw_example` folder first.
+
+1. Build the software locally to test the cross-compilation process. 
+   A debug build directory is created first.
+
+   ```sh 
+   mkdir build-Debug-BBB
+   cd build-Debug-BBB
+   ```
+
+2. Configure the build system. On Linux, run the following command:
+
+   ```sh
+   cmake -G "Unix Makefiles" -DOS_FSFW=linux -DTGT_BSP=arm/beagleboneblack -DLINUX_CROSS_COMPILE=ON -DCMAKE_BUILD_TYPE=Debug ..
+   ```
+
+   On Windows, replace `-G "Unix Makefiles"` with `-G "MinGW Makefiles"`.
+
+   Alternatively, you can use the helper shell scripts located inside `cmake/scripts/BBB/crosscompile`
+   or the Python helper script `cmake_build_config.py` inside the `cmake/scripts` folder.
+   The `BBB` folder also contains template shell files which can be `source`d
+   to quickly set up the environmental variables if you want to keep the system path clean.
+
+3. Run the binary to test it
+
+   ```sh
+   scp fsfw_example <username>@beaglebone.local:/home/fsfw_example
+   ssh <username>@beaglebone.local
+   ./fsfw_example
+   ```
+
+### Setting up Eclipse for a BBB remote target
+
+It is recommended to use the provided Eclipse project files and
+launch configurations to have a starting point. See the specific section in
+the [Eclipse README](README-eclipse.md#top) for information how to do this.
+
+#### Windows
+
+There are some additional steps necessary on Windows: The cross-compiler by 
+default is configured to look for the cross-compiler in `/opt/cross-pi-gcc/bin`. 
+The toolchain path needs to be corrected, for example like shown in the following image:
+
+<img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%">
+
+## Setting up the TCF agent on the BBB
+
+It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable
+Eclipse remote debugging. The following steps show how to setup the TCF agent 
+on the Raspberry Pi and add it to the auto-startup applications. The steps are taken
+from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
+
+1. Install required packages on the RPi
+
+   ```sh
+   sudo apt-get install git uuid uuid-dev libssl-dev
+   ```
+
+2. Clone the repository and perform some preparation steps
+   ```sh
+   git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
+   cd org.eclipse.tcf.agent.git/agent
+   ```
+
+3. Build the TCF agent
+   ```sh
+   make
+   ```
+
+   and then test it by running
+
+   ```sh
+   obj/GNU/Linux/arm/Debug/agent –S
+   ```
+
+4. Finally install the agent for auto-start with the following steps. And set it up for 
+   auto-start.
+
+   ```sh
+   cd org.eclipse.tcf.agent/agent
+   make install
+   sudo make install INSTALLROOT=
+   sudo update-rc.d tcf-agent defaults
+   ```
+
+The [Eclipse README](README-eclipse.md#top) specifies how to perform remote 
+debugging using the TCF agent.
+
+# <a id="troubleshooting"></a> Troubleshooting
+
+## Cloning the root filesystem
+
+There might be some issues with the pthread symbolic links.
+Navigate to the folder containing the symlinks
+
+```sh
+cd <rootfs_path>/usr/lib/arm-linux-gnueabihf
+```
+
+Type `more libpthread`, press  `TAB` and check whether the symbolic 
+link `libpthread.so` is shown. If it is not, we are going to set it up
+manually to avoid issues when linking against `pthread` later. 
+Now you can find out where `libpthread.so` points with `readlink libpthread.so`.
+This information is used to convert the absolute symlink to relative ones, for example with:
+
+Run the following command to copy the symlink `libpthread.so.0` if it does not exist yet:
+
+```sh
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libpthread.so .
+```
+
+Alternatively, you can correct the symlinks to use relative paths, for example with:
+
+```sh
+ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so
+ln -s ../../../lib/arm-linux-gnueabihf/librt.so.1 librt.so
+```
+
+Please note that there might also be issues with some symlinks or libraries not being copied 
+properly, especially on Windows. This has occured with files like `libc.so.6`.
+If there are linker issues at a later stage, you can try to copy the symlinks manually from the
+Linux board to the sysroot with `scp`.
+
+For example, you can copy `libc.so.6` from the Linux board to the sysroot with 
+the following command
+
+If there are issues with the cross-compilation process, manually copying the following
+symlinks can help:
+
+```sh
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libc.so <rootfs_path>/usr/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libc.a <rootfs_path>/usr/lib/arm-linux-gnueabihf
+
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/librt.a <rootfs_path>/usr/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/librt.so <rootfs_path>/usr/lib/arm-linux-gnueabihf
+
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/librt.so.1 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/libpthread.so.0 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/ld-linux-armhf.so.3 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/libc.so.6 <rootfs_path>/lib/arm-linux-gnueabihf
+```
+
+If any custom libraries are used which rely on symlinks, it might be necessary to copy them
+or create them manually as well.

doc/README-rpi.md

@@ -1,41 +1,43 @@
 <img align="center" src="./images/rpi/RPi-Logo-Landscape-Reg-PRINT.png" width="30%">
 
-<sub><sup>Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/). Raspberry Pi is a trademark of the Raspberry Pi Foundation</sup></sub>
+<sub><sup>Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/).
+Raspberry Pi is a trademark of the Raspberry Pi Foundation</sup></sub>
 
 # Getting started on the Raspberry Pi
 
 The FSFW can be run on a Raspberry Pi with the Linux OSAL, using
-an ARM linux cross compiler. Instructions will be provided on how 
+an ARM linux (cross) compiler. Instructions will be provided on how 
 to do this.
 
 ## General Information
 
-The following instructions will show how to install the cross compiler on
+The following instructions will show how to build the example on the Raspberry Pi directly.
-a host machine and mirror the Rapsberry Pi sysroot folder on the host machine
+It will also show how to cross-compile on a host machine and mirror the Raspberry Pi sysroot folder
-so that the same libraries and headers used on the Raspberry Pi are used
+on the host machine so that the same libraries and headers used on the RPi are used
-for the cross-compilation process. The provided Eclipse project files
+for the cross-compilation process.
-and launch configurations also provide a starting point to perform
+
-remote debugging on a Raspberry Pi, using a SSH connection.
+Some Eclipse project files were provided as well to help with setting up the indexer in Eclipse
+more quickly.
 
 ## Prerequisites for direct compilation and cross-compiling
 
 1. SSH connection to the Raspberry Pi working 
 2. Raspberry Pi linux environment set up properly
-3. CMake and rsync installed
+3. `CMake` installed
 
 ## Setting up general prerequisites for Linux systems
 
-1. Install CMake and rsync
+1. Install `CMake` and `rsync`
-    
+
     ```sh
     sudo apt-get install cmake rsync
     ```
-  
+
 2. Configure the Raspberry Pi Linux environment. The last section of the 
-   [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and is
+   [Linux README](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and 
-   also applicable to the Raspberry Pi. SSH into the Raspberry Pi and 
+   is also applicable to the Raspberry Pi. SSH into the Raspberry Pi and 
    follow the instructions in that section.
-   
+ 
 3. Install the `gpiod` library
 
    ```sh
@@ -62,10 +64,8 @@ These prerequisites are valid for Linux as well as Windows hosts.
 
 1. ARM Linux cross compiler installed
 2. Raspberry Pi sysroot folder mirrored on the host machine, using `rsync`
-3. gdb-multiarch installed on host for remote debugging or TCF agent running on Raspberry Pi
+3. gdb-multiarch installed on host for remote debugging or `tcf-agent` running on Raspberry Pi
-   
 
-   
 ## Cross-Compiling on a Linux Host
 
 Steps tested for Ubuntu 20.04. Adapt accordingly for used Linux distribution.
@@ -76,7 +76,6 @@ based on Debian buster is used. If this is not the case, it is recommended to
 follow the steps in the stackoverflow post above and to make sure that the 
 toolchain binaries are added to the path accordingly.
 
-
 ### Setting up prerequisites for cross-compiling
 
 1. Install the pre-built ARM cross-compile with the following command
@@ -84,31 +83,30 @@ toolchain binaries are added to the path accordingly.
     ```sh
     wget https://github.com/Pro/raspi-toolchain/releases/latest/download/raspi-toolchain.tar.gz
     ```
-    
+
-    Please note that this version of the toolchain might become obsolete in the future.
+   Please note that this version of the toolchain might become obsolete in the future.
-    If another toolchain installation is used, it is still recommended to unpack the toolchain in the 
+   If another toolchain installation is used, it is still recommended to unpack the toolchain in the 
-    `/opt/cross-pi-gcc` folder so that the Eclipse configuration and helper 
+   `/opt/cross-pi-gcc` folder so that the Eclipse configuration and helper 
-	scripts work without adaptions. Add the folder to the system path. On Linux,
+   scripts work without adaptions. Add the folder to the system path. On Linux,
-    this can generally be done with the following command
+   this can generally be done with the following command
-    
+
-    ```sh
+   ```sh
-    export PATH=$PATH:"/opt/cross-pi-gcc/bin"
+   export PATH=$PATH:"/opt/cross-pi-gcc/bin"
-    ``` 
+   ``` 
-    
+
-    You can add this line to the `.bashrc` or `.profile` file in the `$HOME` directory 
+   You can add this line to the `.bashrc` or `.profile` file in the `$HOME` directory 
-    to add environmental variables permanently. More experienced users can
+   to add environmental variables permanently. More experienced users can
-	perform this step is a shell script which is `source`d to keep the environment clean.
+   perform this step is a shell script which is `source`d to keep the environment clean.
-    
+
-    Test the toolchain with the following command
+   Test the toolchain with the following command
-    
+
-    ```sh
+   ```sh
-    arm-linux-gnueabihf-gcc --version
+   arm-linux-gnueabihf-gcc --version
-    ``` 
+   ``` 
-     
+
-    
 2. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
    the Raspberry Pi is working without issues. Then perform the following steps
-   
+
    ```sh
    cd ~
    mkdir raspberrypi
@@ -117,39 +115,56 @@ toolchain binaries are added to the path accordingly.
    cd rootfs 
    pwd
    ```
-   
+
    The result of the `pwd` command will be used later to sync the root file
    system of the Raspberry Pi to the host machine.
    With a Raspberry Pi 4, you can replace `<ip-address>` with `raspberrypi.local` and 
    when using the default rootfs path, you can replace `<rootfs-path>` with
    `$HOME/raspberrypi/rootfs`.
-   
+
    ```sh
-   rsync -vR --progress -rl --delete-after --safe-links pi@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
+   rsync -avHAXR --numeric-ids --info=progress2 <username>@<ip-address>:/{lib,usr} <rootfs-path>
    ```
-   
+
-   Please note that there might be issues with some symlinks or libraries not being copied properly.
+   On Linux, it is recommended to repair some symlinks which can be problematic:
-   This has occured with files like `libc.so.6`. If there are linker issues at a later stage,
+   Navigate to the folder containing the symlinks first:
-   you can try to rerun `rsync` without the`--safe-links` flag or copy the shared libraries or 
+
-   symlinks manually from the Raspberry Pi to the sysroot with `scp`.
-   
-   For example, you can copy `libc.so.6` from the Raspberry Pi to the sysroot with 
-   the following command
-   
    ```sh
-   scp pi@<ip-address>:lib/arm-linux-gnueabihf/lib.so.6 <rootfs-path>/lib/arm-linux-gnueabihf
+   cd <rootfs_path>/usr/lib/arm-linux-gnueabihf
    ```
-   
+
+   You can now use
+
+   ```sh
+   readlink libpthread.so
+   ```
+
+   which will show an absolute location of a shared library the symlinks points to. This location
+   needs to be converted into a relative path.
+
+   Run the following command to create a relative symlinks instead of an absolute ones. The pointed
+   to location might change to check it with `readlink` first before removing the symlinks:
+
+   ```sh
+   rm libpthread.so
+   rm librt.so
+   ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so
+   ln -s ../../../lib/arm-linux-gnueabihf/librt.so.1 librt.so
+   ```
+
+   For more information on issues which can occur when cloning the root filesystem,
+   see the [troubleshooting](#troubleshooting) section.
+
 3. It is recommended to install `gdb-multiarch`. This tool will allow remote debugging
-   on the host computer.  You don't need to do this if the TCF agent is used.
+   on the host computer. This step is not required if the `tcf-agent` is used.
-   
+
    ```sh
    sudo apt-get install gdb-multiarch
    ```
 
 4. Perform the steps [in the cross-compile section](#cross-test) to build the 
    software for the Raspberry Pi and test it.
-   
+
 ## Cross-Compiling on a Windows Host
 
 ### Additional Prerequites
@@ -168,7 +183,7 @@ toolchain binaries are added to the path accordingly.
    ```
    pacman -S mingw-w64-x86_64-cmake rsync
    ```
-   
+
 2. Configure the Raspberry Pi linux environment. The last section of the 
    [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment 
    for the FSFW and isalso applicable to the Raspberry Pi. SSH into the 
@@ -178,14 +193,14 @@ toolchain binaries are added to the path accordingly.
    You can find out the distribution release of your Raspberry Pi by running `cat /etc/rpi-issue`.
 
    Test the toolchain by running:
-  
+
    ```sh
    arm-linux-gnueabihf-gcc --version
    ``` 
 
 4. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
    the Raspberry Pi is working without issues. Then perform the following steps
-   
+
    ```sh
    cd /c/Users/<UserName>
    mkdir raspberrypi
@@ -194,81 +209,62 @@ toolchain binaries are added to the path accordingly.
    cd rootfs
    pwd
    ```
-   
+
    Store the result of `pwd`, it is going to be used by `rsync` later.
-   
+
    Now use rsync to clone the Rapsberry Pi sysroot to the local host machine.
    With a Raspberry Pi 4, you can replace `<ip-address>` with `raspberrypi.local`.
    Use the rootfs location stored from the previous steps as `<rootfs-path>`.
-   
+
    ```sh
    rsync -vR --progress -rl --delete-after --safe-links pi@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
    ```
-   
+
-5. There might be some issues with the pthread symbolic links. Navigate to the folder
+   Please note that `rsync` sometimes does not copy shared libraries or symlinks properly,
-   containing the symlinks
+   which might result in errors when cross-compiling and cross-linking. It is recommended to run
-   
+   the following commands in addition to the `rsync` command on Windows:
+
    ```sh
-   cd /c/User/<UserName>/raspberrypi/rootfs/usr/lib/arm-linux-gnueabihf
+   scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/{libc.so.6,ld-linux-armhf.so.3,libm.so.6} <rootfs_path>/lib/arm-linux-gnueabihf
+   scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/{libpthread.so,libc.so,librt.so} <rootfs_path>/usr/lib/arm-linux-gnueabihf
    ```
-   
+
-   Type `more libpthread`, press  `TAB` and check whether the symbolic 
+   For more information on issues which can occur when cloning the root filesystem,
-   link `libpthread.so` is shown. If it is not, we are going to set it up
+   see the [troubleshooting](#troubleshooting) section.
-   manually to avoid issues when linking against `pthread` later. 
+
-   
+5. It is recommended to install `gdb-multiarch`. This tool will allow remote debugging on the host 
-   Run the following command to create a symlink to `libpthread.so.0`
+   computer. Replace `x86_64` with the correct processor architecture for other architectures.
-   
+   This is not required if the `tcf-agent` is used.
-   ```sh
+
-   ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so 
-   ```
-   
-   Please note that there might also be issues with some symlinks or libraries not being copied 
-   properly. This has occured with files like `libc.so.6`. If there are linker issues at a later 
-   stage, you can try to rerun `rsync` without `--safe-links` or copy the shared libraries or 
-   symlinks manually from the Raspberry Pi to the sysroot with `scp`.
-   
-   For example, you can copy `libc.so.6` from the Raspberry Pi to the sysroot with 
-   the following command
-   
-   ```sh
-   scp pi@<ip-address>:lib/arm-linux-gnueabihf/lib.so.6 <rootfs-path>/lib/arm-linux-gnueabihf
-   ```
-   
-6. It is recommended to install `gdb-multiarch`. 
-   This tool will allow remote debugging on the host computer. Replace
-   `x86_64` with the correct processor architecture for other architectures.
-   
    ```sh
    pacman -S mingw-w64-x86_64-gdb-multiarch
    ```
 
-7. Perform the steps [in the following chapter](#cross-test) to build the
+6. Perform the steps [in the following chapter](#cross-test) to build the
    software for the Raspberry Pi and test it.
-  
+
 ## <a id="cross-test"></a> Testing the cross-compilation
 
 It is recommended to set the following environmental variables for the CMake build:
    - `CROSS_COMPILE`: Explicitely specify the name of the cross compiler 
    - `RASPBERRY_VERSION`: Explicitely specify the version of the Raspberry Pi
    - `RASPBIAN_ROOTFS`: Explicitely set the path to the local RPi rootfs
-   
+
 For example with the following commands
-   
+
 ```sh
 export CROSS_COMPILE="arm-linux-gnueabihf"
 export RASPBERRY_VERSION="4"
 export RASPBIAN_ROOTFS="<pathToRootFS>"
 ```
-   
+
-   
 It is recommended to test whether the environmental variables were set correctly,
 for example by running
-   
+
 ```sh
 echo $RASPBIAN_ROOTFS
 ```
 
-
 These variables can either be set every time before a debugging session to
 keep the environment clean (should be done before starting Eclipse)
 or permanently by adding the `export` commands to system files.
@@ -285,32 +281,32 @@ the software, Eclipse will have the system variables from Windows,
 so it is recommended to either permanently set the three environmental
 variables in the Windows system environmental variables or add them in
 Eclipse. See the [Eclipse README](README-eclipse.md#top) for more information.
-   
+
 Now we can test whether everything was set up properly by compiling the example
 and running it on the Raspberry Pi via command line. 
 Navigate into the `fsfw_example` folder first. 
 
 1. Build the software locally to test the cross-compilation process. 
    We are going to create a Debug build directory first.
-   
+
    ```sh 
    mkdir build-Debug-RPi
    cd build-Debug-RPi
    ```
-   
+
 2. Configure the build system. On Linux, run the following command:
-	
+
    ```sh
    cmake -G "Unix Makefiles" -DOS_FSFW=linux -DTGT_BSP=arm/raspberrypi -DLINUX_CROSS_COMPILE=ON -DCMAKE_BUILD_TYPE=Debug ..
    ```
-   
+
    On Windows, replace `-G "Unix Makefiles"` with `-G "MinGW Makefiles"`.
-   
+
    Alternatively, you can use the helper shell scripts located inside `cmake/scripts/RPi/crosscompile`
    or the Python helper script `cmake_build_config.py` inside the `cmake/scripts` folder.
    The `RPi` folder also contains template shell files which can be `source`d
    to quickly set up the environmental variables if you want to keep the system path clean.
-   
+
 3. Run the binary to test it
 
    ```sh
@@ -318,13 +314,13 @@ Navigate into the `fsfw_example` folder first.
    ssh pi@raspberrypi.local
    ./fsfw_example
    ```
-   
+
 ### Setting up Eclipse for a Raspberry Pi remote target
 
 It is recommended to use the provided Eclipse project files and
 launch configurations to have a starting point. See the specific section in
 the [Eclipse README](README-eclipse.md#top) for information how to do this.
-  
+
 #### Windows
 
 There are some additional steps necessary on Windows: The cross-compiler by 
@@ -333,7 +329,6 @@ The toolchain path needs to be corrected, for example like shown in the followin
 
 <img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%">
 
-
 ## Setting up the TCF agent on the Raspberry Pi
 
 It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable
@@ -346,28 +341,27 @@ from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
    ```sh
    sudo apt-get install git uuid uuid-dev libssl-dev
    ```
-   
+
 2. Clone the repository and perform some preparation steps
    ```sh
    git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
    cd org.eclipse.tcf.agent.git/agent
-   cp -R machine/arm machine/armv6l
    ```
-   
+
 3. Build the TCF agent
    ```sh
    make
    ```
-   
+
    and then test it by running
-   
+
    ```sh
-   obj/GNU/Linux/armv6l/Debug/agent –S
+   obj/GNU/Linux/arm/Debug/agent –S
    ```
-   
+
-4. Finally instal lthe agent for auto-start with the following steps. The last step
+4. Finally instal lthe agent for auto-start with the following steps and set it up for auto-start.
-   did not work on a Rapsberry Pi 4, but apparentely was not necessary.
+   The last step did not work on a Rapsberry Pi 4, but apparentely was not necessary.
-   
+
    ```sh
    cd org.eclipse.tcf.agent/agent
    make install
@@ -375,6 +369,63 @@ from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
    sudo update-rc.d tcf-agent defaults
    sudo update-rc.d tcf-agent enable 2
    ```
-   
+
 The [Eclipse README](README-eclipse.md#top) specifies how to perform remote 
 debugging using the TCF agent.
+
+# <a id="troubleshooting"></a> Troubleshooting
+
+## Cloning the root filesystem
+
+There might be some issues with the pthread symbolic links.
+Navigate to the folder containing the symlinks
+
+```sh
+cd <rootfs_path>/usr/lib/arm-linux-gnueabihf
+```
+
+Type `more libpthread`, press  `TAB` and check whether the symbolic 
+link `libpthread.so` is shown. If it is not, we are going to set it up
+manually to avoid issues when linking against `pthread` later. 
+Now you can find out where `libpthread.so` points with `readlink libpthread.so`.
+This information is used to convert the absolute symlink to relative ones, for example with:
+
+Run the following command to copy the symlink `libpthread.so.0` if it does not exist yet:
+
+```sh
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libpthread.so .
+```
+
+Alternatively, you can correct the symlinks to use relative paths, for example with:
+
+```sh
+ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so
+ln -s ../../../lib/arm-linux-gnueabihf/librt.so.1 librt.so
+```
+
+Please note that there might also be issues with some symlinks or libraries not being copied 
+properly, especially on Windows. This has occured with files like `libc.so.6`.
+If there are linker issues at a later stage, you can try to copy the symlinks manually from the
+Linux board to the sysroot with `scp`.
+
+For example, you can copy `libc.so.6` from the Linux board to the sysroot with 
+the following command
+ 
+If there are issues with the cross-compilation process, manually copying the following
+symlinks can help:
+
+```sh
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libc.so <rootfs_path>/usr/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/libc.a <rootfs_path>/usr/lib/arm-linux-gnueabihf
+
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/librt.a <rootfs_path>/usr/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/usr/lib/arm-linux-gnueabihf/librt.so <rootfs_path>/usr/lib/arm-linux-gnueabihf
+
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/librt.so.1 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/libpthread.so.0 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/ld-linux-armhf.so.3 <rootfs_path>/lib/arm-linux-gnueabihf
+scp <user_name>@<ip-address>:/lib/arm-linux-gnueabihf/libc.so.6 <rootfs_path>/lib/arm-linux-gnueabihf
+```
+
+If any custom libraries are used which rely on symlinks, it might be necessary to copy them
+or create them manually as well.

generators/modgen

@@ -1 +1 @@
-Subproject commit b2f7cb79e9ab1f21748d84f3a7de8a0a75458531
+Subproject commit 403bdd15b6175685ca2d45fed648812445483a40

misc/eclipse/.project

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <projectDescription>
-	<name>fsfw_example</name>
+	<name>fsfw_example_public</name>
 	<comment></comment>
 	<projects>
 	</projects>