Build & Install

The akr2daq3 server software is to be cross compiled for the ZC706 [1] board. Therefore a cross compiler is needed. The following sections describes all requirements and steps to install.

Requirements

The server software is build within a linux system. Since we build the software not directly on the ZC706 we have to cross-compile for the Arm [2] platform. To do this the following requirements must be met:

• This repository

• CMake [3] - build system used by the server software

• needed libraries have to be installed on the ZC706

• GCC cross compiler

• Copy of parts of the root filesystem (rootfs)

• (optional) automatic SSH access to ZC706 via public key

Clone repository

Clone the repository to your local machine and initialize the submodules.

git clone git@gitlab.mn.tu-dresden.de:wket/hardware/fpga-zc706/zc706-server.git
git submodule update --init

Install CMAKE

To install CMake in an Ubuntu system run the following:

apt install cmake

Install needed libraries on the ZC706

The ZC706 needs the build-essential package to be installed. Therefore SSH into the ZC706 and install the package using root rights.

ssh debian@ZC706.local

After that you can install the package.

sudo apt install build-essential

For some reasons some symbolic links of libraries are absolute. This is a problem when trying to cross compile. Therefore we need to fix it using the symlinks tool

sudo apt install symlinks
cd /usr/lib/arm-linux-gnueabihf
sudo symlinks -rc .

Another thing which needs to be done ist the following:

cd /usr/lib
sudo ln -s arm-linux-gnueabihf/crt1.o crt1.o
sudo ln -s arm-linux-gnueabihf/crti.o crti.o
sudo ln -s arm-linux-gnueabihf/crtn.o crtn.o
cd arm-linux-gnueabihf
sudo ln -s libstdc++.so.6 libstdc++.so

This is needed so that all libraries are found when building the software.

The last thing to do on the ZC706 is to create the directory which should contain the server application.

mkdir -p ~/app

GCC cross compiler

A cross compiler tool chain may be found at developer.arm.com. On the currently used system at the AKR-2 [4] the version arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf is used. Make sure you use the arm-none-linux-gnueabihf architecture as this is the one running on the ZC706.

To install it simply download it and extract to where ever you like. I suggest within ~/tools/arm-cross-compiler.

Copy parts of the rootfs

The cross compiler needs to know the libraries and includes of the ZC706 to compile and link the final binary. Therefore it is needed to copy those parts of the rootfs from the ZC706 to your system.

The tool of choice to sync your copy of the rootfs with the ZC706 is the command rsync which must be installed on both systems. The ZC706 and the host PC.

sudo apt install rsync

After sync the usr and the lib directory of the ZC706. It is assumed that the ZC706 is reachable using the hostname nexmess.local. Additionally it is assumed the rootfs should be installed to ~/tools/ZC706/rootfs.

mkdir ~/tools/ZC706/rootfs
rsync -rl --delete-after --safe-links debian@nexmess.local:/{lib,usr} ~/tools/ZC706/rootfs

This may take some time.

Automatic SSH access to ZC706 via public key (optional but recommend)

When using a public key it is possible to directly access the ZC706 via SSH without having to enter a password. This makes it easy for the build system to directly copy the final binary onto the ZC706.

If you have not done so already generate a key pair (without passphrase):

ssh-keygen -t ed25519 -C "your-mail@example.com"

Copy the public key to the authorized_keys file of the ZC706.

ssh -T debian@ZC706 'mkdir -p ~/.ssh'
cat ~/.ssh/id_ed25519.pub | ssh -T debian@ZC706 'cat >> ~/.ssh/authorized_keys'

Now you should be able to access the ZC706 without entering a password. You may want to try it:

ssh debian@nexmess.local

Assumptions

This page assumes that the ZC706 is completely configured and running. It is assumed the ZC706 runs a Debian [5] system.

Environment variables

This wiki pages uses environment variables to point to special directories. You don’t have to set them but it makes almost all shown code copyable.

• PROJECT_DIR - directory of the local copy of the git project.

• ROOTFS_DIR - directory of the the copied rootfs of the ZC706

• CROSS_COMPILER_DIR - directory of the cross compiler

Here is an example on how to set the variables.

export PROJECT_DIR=~/projects/daq3zc706-server
export ROOTFS_DIR=~/tools/ZC706/rootfs
export CROSS_COMPILER_DIR=~/tools/arm-cross-compiler/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf

Build the server software

As already mentioned the server software uses CMake to make things easy. It is also possible to directly copy the final binary onto the ZC706 in the correct directory.

Before building the software clone it from the git repository.

git clone git@gitlab.mn.tu-dresden.de:wket/hardware/fpga-zc706/zc706-server.git
git submodule update --init

Configure the project

The project of the server software comes with a configuration example. Copy it to set your configuration.

cd $PROJECT_DIR
cp config/config.cmake.example config/config.cmake

Now edit the file to fit your needs. The following code snippet shows an example of changed settings within the config to match this wiki page.

# .....

set(sysroot_base_path $ENV{HOME}/tools/ZC706/rootfs)
set(toolchain_path $ENV{HOME}/tools/arm-cross-compiler/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-linux-gnueabihf)

# ssh copy config
# this only works if you can log in on the target device without password (via public key)
# set ssh_copy to FALSE to turn this off
# set ssh_auto_restart to FALSE to not automatically restart the service
set(ssh_copy TRUE)
set(ssh_auto_restart_service TRUE)
set(ssh_user debian)
set(ssh_host zc706)
set(ssh_target_dir /home/debian/app)

# .....

You can see that the rootfs directory is set to sysroot_base_path, the cross compiler directory is set to toolchain_path and that user specific settings for the ZC706 are made. When settings ssh_copy to TRUE the finished binary is directly copied to the ZC706 in the set directory (/home/debian/app in this case). To make this possible you must be able to access the ZC706 without credentials.

When setting ssh_auto_restart_service to true the service is automatically stopped before copying the software to the ZC706. After copying the service will start again automatically. To be able to do that you must configure the software as service and allow the *debian* user to restart the service without password.

Build the software

There are two simple scripts to compile the project.

• compile_debug - Compiles the debug version of the server software

• compile_release - Compiles the release version of the server software

Simply run one of the scripts and the software is build and depending on the configuration copied to the ZC706. The following snippet shows how to compile the release version.

./compile_release

Start server software automatically on boot

When actually planning to do measurements using the whole system it is wise to not bother with the ZC706 at all. So the server software should start automatically. Like this the measurements may start as soon as the green LED lights up.

To do this systemd [6] is used. Therefore a .service script must be placed into /etc/systemd/system. The project provides scripts for akr2daq3. So all you have to do is to copy them onto ZC706. You need root rights to do this so it has to be done in more than one step. First copy the script onto the ZC706.

scp $PROJECT_DIR/scripts/systemctl/akr2daq3.service debian@ZC706.local:/tmp/

Once the file is copied SSH into the ZC706 and log yourself in. Then switch to the root user using sudo su and do he following:

nano /tmp/akr2daq3.service

Set the correct path for ExecStart. Save and close the file (CTRL+O -> CTRL+X).

Then:

mv /tmp/akr2daq3.service /etc/systemd/system/
systemctl enable akr2daq3.service

You may control the server software using the following commands if you feel there is a need for it:

systemctl start akr2daq3.service
systemctl stop akr2daq3.service
systemctl restart akr2daq3.service

Assuming the server software is not running you can test if everything is fine by starting the software using the start command. The green LED should turn on. It should turn off again if you use the stop command. The green LED should turn on after about 30s after booting the ZC706.

Allow user to restart service

When following the previous section it is a good idea to allow the debian user to restart the service, too. To du that login as root and run the following command:

visudo

Add the following lines at the end of the file:

debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl start akr2daq3
debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl stop akr2daq3
debian ALL=(ALL:ALL) NOPASSWD: /bin/systemctl restart akr2daq3

Like this you can simply control the server as the debian user using sudo without any password. It is possible to automatically upload and restart the service when building the server software, too.

Build the documentation

The documentation is automatically build on each push to the main branch. You can also build it manually.

The documentation requires Doxygen [7] and Python [8] to be installed on your system. To install it run the following command:

sudo apt install doxygen python3

Then you can build the documentation running the script make_doc:

./make_doc

The documentation will be available within the html directly.

Bibliography

[1]

AMD Zynq 7000 SoC ZC706 Evaluation Kit

[2]

Arm

[3]

CMake

[4]

AKR-2

[5]

Debian

[6]

systemd

[7]

Doxygen

[8]

Python