diff --git a/README.md b/README.md index 1cdeda7..f6f9957 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,18 @@ These files can be edited manually after `CMake` build generation. [Getting started with the Raspberry Pi](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
[Getting started with the Beagle Bone Black](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
+# Getting started on the Raspberry Pi + +THe README so setup and run the example on a Raspberry Pi can be found in the following file + +[Getting started on the Raspberry Pi](doc/README-rpi.md#top) + +# Getting started on the Beagle Bone Black + +THe README so setup and run the example on a Beagle Bone Black can be found in the following file + +[Getting started on the Beagle Bone Black](doc/README-bbb.md#top) + # Linux - Enabling RTOS functionalities The last chapter in the [Linux README](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu) diff --git a/doc/README-bbb.md b/doc/README-bbb.md new file mode 100644 index 0000000..4350668 --- /dev/null +++ b/doc/README-bbb.md @@ -0,0 +1,411 @@ + + +Image taken from [Beagle Board website](https://beagleboard.org/logo) and used in +accordance with their trademark rules. + +# 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 `` with `beaglebone.local` to use DNS. + Use the rootfs location stored from the previous steps as ``. + + ```sh + rsync -avHAXR --delete-after --info=progress2 --numeric-ids @:/{usr,lib} + ``` + + On Linux, it is recommended to repair some symlinks which can be problematic: + Navigate to the folder containing the symlinks first: + + ```sh + cd /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 `` 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/ + 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 `` with `beaglebone.local` to use DNS. + Use the rootfs location stored from the previous steps as ``. + + ```sh + rsync -avHAXR --numeric-ids --info=progress2 @:/{lib,usr} + ``` + + 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 @:/lib/arm-linux-gnueabihf/{libc.so.6,ld-linux-armhf.so.3,libm.so.6} /lib/arm-linux-gnueabihf + scp @:/usr/lib/arm-linux-gnueabihf/{libpthread.so,libc.so,librt.so} /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. + +## 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 @beaglebone.local:/home/fsfw_example + ssh @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: + + + +## 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. + +# Troubleshooting + +## Cloning the root filesystem + +There might be some issues with the pthread symbolic links. +Navigate to the folder containing the symlinks + +```sh +cd /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 @:/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 @:/usr/lib/arm-linux-gnueabihf/libc.so /usr/lib/arm-linux-gnueabihf +scp @:/usr/lib/arm-linux-gnueabihf/libc.a /usr/lib/arm-linux-gnueabihf + +scp @:/usr/lib/arm-linux-gnueabihf/librt.a /usr/lib/arm-linux-gnueabihf +scp @:/usr/lib/arm-linux-gnueabihf/librt.so /usr/lib/arm-linux-gnueabihf + +scp @:/lib/arm-linux-gnueabihf/librt.so.1 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/libpthread.so.0 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/ld-linux-armhf.so.3 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/libc.so.6 /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. diff --git a/doc/README-rpi.md b/doc/README-rpi.md new file mode 100644 index 0000000..ebb7e38 --- /dev/null +++ b/doc/README-rpi.md @@ -0,0 +1,437 @@ + + +Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/). +Raspberry Pi is a trademark of the Raspberry Pi Foundation + +# 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 +to do this. + +## General Information + +The following instructions will show how to build the example on the Raspberry Pi directly. +It will also show how to cross-compile on a host machine and mirror the Raspberry Pi sysroot folder +on the host machine so that the same libraries and headers used on the RPi 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 Raspberry Pi working +2. Raspberry Pi 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 Raspberry Pi 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 Raspberry Pi. SSH into the Raspberry Pi and + follow the instructions in that section. + +3. Install the `gpiod` library + + ```sh + sudo apt-get install gpiod libgpiod-dev + ``` + +## Getting started on the Raspberry Pi + +Make sure to follow the steps above. Now you should be able to build the software on +the Raspberry Pi. A ssh connection to the Raspberry Pi is assumed here + +You can build the software with the following commands + +```sh +mkdir build-Debug-RPi +cd build-Debug-RPi +cmake -DOS_FSFW=linux -DTGT_BSP=arm/raspberrypi -DLINUX_CROSS_COMPILE=OFF -DCMAKE_BUILD_TYPE=Debug .. +cmake --build . -j +``` + +## Prerequisites for cross-compiling + +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 + +## Cross-Compiling on a Linux Host + +Steps tested for Ubuntu 20.04. Adapt accordingly for used Linux distribution. +The following steps are based on this +[stackoverflow post](https://stackoverflow.com/questions/19162072/how-to-install-the-raspberry-pi-cross-compiler-on-my-linux-host-machine). +For the steps show here, we are also going to assume that a new Raspbian image +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 + + ```sh + wget https://github.com/Pro/raspi-toolchain/releases/latest/download/raspi-toolchain.tar.gz + ``` + + Then extract to the opt folder: + + ```sh + sudo tar xfz raspi-toolchain.tar.gz --strip-components=1 -C /opt + ``` + + 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 + `/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, + this can generally be done with the following command + + ```sh + export PATH=$PATH:"/opt/cross-pi-gcc/bin" + ``` + + You can add this line to the `.bashrc` or `.profile` file in the `$HOME` directory + 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. + + Test the toolchain with the following command + + ```sh + 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 + cd raspberrypi + mkdir rootfs + 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 `` with `raspberrypi.local` and + when using the default rootfs path, you can replace `` with + `$HOME/raspberrypi/rootfs`. + + ```sh + rsync -avHAXR --numeric-ids --info=progress2 @:/{lib,usr,opt/vc/lib} + ``` + + On Linux, it is recommended to repair some symlinks which can be problematic: + Navigate to the folder containing the symlinks first: + + ```sh + cd /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. 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 + +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 `` 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 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 + Raspberry Pi and follow the instructions in that section. + +3. Install the correct [ARM Linux cross-compile toolchain provided by SysProgs](https://gnutoolchains.com/raspberry/). + 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/ + mkdir raspberrypi + cd raspberrypi + 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 Rapsberry Pi sysroot to the local host machine. + With a Raspberry Pi 4, you can replace `` with `raspberrypi.local`. + Use the rootfs location stored from the previous steps as ``. + + ```sh + rsync -vR --progress -rl --delete-after --safe-links pi@:/{lib,usr,opt/vc/lib} + ``` + + 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 @:/lib/arm-linux-gnueabihf/{libc.so.6,ld-linux-armhf.so.3,libm.so.6} /lib/arm-linux-gnueabihf + scp @:/usr/lib/arm-linux-gnueabihf/{libpthread.so,libc.so,librt.so} /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 Raspberry Pi and test it. + +## 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="" +``` + +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. + +A helper script has been provided in `cmake/scripts/RPi` 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 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 + scp fsfw_example pi@raspberrypi.local:/home/pi/fsfw_example + 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 +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: + + + +## 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 +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 instal lthe agent for auto-start with the following steps and set it up for auto-start. + 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 + sudo make install INSTALLROOT= + 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. + +# Troubleshooting + +## Cloning the root filesystem + +There might be some issues with the pthread symbolic links. +Navigate to the folder containing the symlinks + +```sh +cd /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 @:/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 @:/usr/lib/arm-linux-gnueabihf/libc.so /usr/lib/arm-linux-gnueabihf +scp @:/usr/lib/arm-linux-gnueabihf/libc.a /usr/lib/arm-linux-gnueabihf + +scp @:/usr/lib/arm-linux-gnueabihf/librt.a /usr/lib/arm-linux-gnueabihf +scp @:/usr/lib/arm-linux-gnueabihf/librt.so /usr/lib/arm-linux-gnueabihf + +scp @:/lib/arm-linux-gnueabihf/librt.so.1 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/libpthread.so.0 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/ld-linux-armhf.so.3 /lib/arm-linux-gnueabihf +scp @:/lib/arm-linux-gnueabihf/libc.so.6 /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.