updated README
This commit is contained in:
parent
6eeaa6f594
commit
bf0d0d7d86
12
README.md
12
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)<br>
|
[Getting started with the Raspberry Pi](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)<br>
|
||||||
[Getting started with the Beagle Bone Black](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)<br>
|
[Getting started with the Beagle Bone Black](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)<br>
|
||||||
|
|
||||||
|
# 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
|
# Linux - Enabling RTOS functionalities
|
||||||
|
|
||||||
The last chapter in the [Linux README](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
|
The last chapter in the [Linux README](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
|
||||||
|
|||||||
411
doc/README-bbb.md
Normal file
411
doc/README-bbb.md
Normal file
@ -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.
|
||||||
437
doc/README-rpi.md
Normal file
437
doc/README-rpi.md
Normal file
@ -0,0 +1,437 @@
|
|||||||
|
<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>
|
||||||
|
|
||||||
|
# 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 `<ip-address>` with `raspberrypi.local` and
|
||||||
|
when using the default rootfs path, you can replace `<rootfs-path>` with
|
||||||
|
`$HOME/raspberrypi/rootfs`.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
rsync -avHAXR --numeric-ids --info=progress2 <username>@<ip-address>:/{lib,usr,opt/vc/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.
|
||||||
|
|
||||||
|
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 `<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 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/<UserName>
|
||||||
|
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 `<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>
|
||||||
|
```
|
||||||
|
|
||||||
|
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 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.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
<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
|
||||||
|
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.
|
||||||
|
|
||||||
|
# <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.
|
||||||
Loading…
Reference in New Issue
Block a user