HALCS Installation

Repositories and Releases

This project is hosted on Github, at the following link: HALCS Github Repository.

Here a list of resources that you can find on the project page:

Releases [1]
Contains the .rpm packages for installing HALCS on a CentOS/RedHat/Fedora and the .pdf documentation for every official release.
Repository [2]
Contains the git repository of the project.
[1]https://github.com/lnls-dig/halcs/releases
[2]https://github.com/lnls-dig/halcs

On the repository the official releases have a tag named v#maj.#min.#rev where #maj represent the major release version of the software, #min the minor one and #rev the revision (e.g v1.9.1). This follows semantic versioning as defined in Semantic Versioning. The released binary files follow the same naming convention.

Note

if you got this from the repository (as opposed to a named tar.gz or pdf file) it may happen that you are looking at a later commit than the release this manual claims to document. It is a fact of life that developers forget to re-read and fix documentation while updating the code. In that case, please run git describe HEAD to ensure where you are.

About the source code

Introduction

The HALCS software makes use of two build systems: make [3] and cmake [4]. Both of them should produce the same binaries, but cmake gives you more outputs, such as .deb and .rpm packages. Also, CMake gives you more controlover how binaries are built and is the recommended way.

[3]https://www.gnu.org/software/make
[4]https://cmake.org

Prior to build HALCS, we need to install its dependencies. As of the moment, it makes use of 4 external dependencies:

libsodium 1.0.8
https://github.com/jedisct1/libsodium/tree/1.0.8
zeromq v4.2.5
https://github.com/zeromq/libzmq/tree/v4.2.5
czmq 4.0.2
https://github.com/zeromq/czmq/tree/4.0.2
mlm v1.6.1
https://github.com/lnls-dig/malamute/tree/v1.6.1

Installing dependencies

In order to install them with versions that are known to be compatible use the following snippet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
git clone --branch=1.0.8 https://github.com/jedisct1/libsodium.git && \
git clone --branch=v4.2.5 https://github.com/zeromq/libzmq.git && \
git clone --branch=v4.0.2 https://github.com/zeromq/czmq.git && \
for project in libsodium libzmq czmq; do
    CONFIG_OPTS=()
    CONFIG_OPTS+=("CFLAGS=-Wno-format-truncation")
    CONFIG_OPTS+=("CPPFLAGS=-Wno-format-truncation")
    if [ $project == "libzmq" ]; then
        CONFIG_OPTS+=("PKG_CONFIG_PATH=/usr/local/lib/pkgconfig --with-libsodium")
    fi

    cd $project && \
    ./autogen.sh && \
    ./configure "${CONFIG_OPTS[@]}" && \
    make check && \
    make && \
    sudo make install && \
    sudo ldconfig && \
    cd ..

    # Check last command return status
    if [ $? -ne 0 ]; then
        echo "Could not compile/install project $project." >&2
        exit 1
    fi
done

git clone --branch=v1.6.1 https://github.com/lnls-dig/malamute.git && \
for project in malamute; do
    CONFIG_OPTS=()
    CONFIG_OPTS+=("--with-systemd-units")
    CONFIG_OPTS+=("--sysconfdir=/usr/etc")
    CONFIG_OPTS+=("--prefix=/usr")
    CONFIG_OPTS+=("CFLAGS=-Wno-format-truncation")
    CONFIG_OPTS+=("CPPFLAGS=-Wno-format-truncation")

    cd $project && \
    ./autogen.sh && \
    ./configure "${CONFIG_OPTS[@]}" && \
    make check && \
    make && \
    sudo make install && \
    sudo ldconfig && \
    cd ..

    MALAMUTE_VERBOSE=0
    MALAMUTE_PLAIN_AUTH=
    MALAMUTE_AUTH_MECHANISM=null
    MALAMUTE_ENDPOINT='ipc:///tmp/malamute'
    MALAMUTE_CFG_FILE=/usr/etc/malamute/malamute.cfg
    # Install our custom Malamute config file
    sudo sed -i \
        -e "s|verbose\( *\)=.*|verbose\1= ${MALAMUTE_VERBOSE}|g" \
        -e "s|plain\( *\)=.*|plain\1= ${MALAMUTE_PLAIN_AUTH}|g" \
        -e "s|mechanism\( *\)=.*|mechanism\1= ${MALAMUTE_AUTH_MECHANISM}|g" \
        -e "s|tcp://\*:9999|${MALAMUTE_ENDPOINT}|g" \
        ${MALAMUTE_CFG_FILE}


    # Enable service
    sudo systemctl enable malamute || /bin/true

    # Check last command return status
    if [ $? -ne 0 ]; then
        echo "Could not compile/install project $project." >&2
        exit 1
    fi
done

Alternatively you can install them via .rpm or .deb packages if available at your distribution. As all of them use semantic versioning, you can install any version that is greater or equal than the specified ones for minor and revision: numbers.

Installing HALCS server

Using CMake Build System

The recommended way to build the source code is to use cmake:

  1. Install make and gcc:
1
sudo apt-get install make gcc

for Debian-based systems.

1
sudo yum install make gcc-c++

for Fedora-based systems.

  1. Install CMake. The supported version is 3.10+. Check you distribution for the correct CMake version:
1
sudo apt-get install cmake

for Debian-based systems.

1
sudo yum install cmake

for Fedora-based systems.

  1. Check CMake version with:
cmake --version

If the reported version is less than 3.10 install it manually with:

1
2
3
4
5
version=3.10
build=3
wget -c https://cmake.org/files/v$version/cmake-$version.$build.tar.gz -O - | \
    tar -xzv
cd cmake-$version.$build/

Compile and install CMake:

1
2
3
./bootstrap
make -j$(nproc)
sudo make install
  1. Get the source code:
1
git clone --recursive https://github.com/lnls-dig/halcs
  1. Go to the source code directory:
1
cd halcs
  1. Build and install the code:
1
2
3
4
5
mkdir -p build
cd build
cmake ../
make
sudo make install

All in all, the full script to install HALCS with cmake is:

1
2
3
4
5
6
7
git clone --recursive https://github.com/lnls-dig/halcs && \
cd halcs && \
mkdir -p build
cd build
cmake ../
make
sudo make install

Optionally you can build HALCS by creating a .deb or .rpm and install them. You can do that by following the instructions:

For Debian-based distributions:

1
2
3
4
5
6
git clone --recursive https://github.com/lnls-dig/halcs && \
cd halcs && \
mkdir -p build
cd build
cmake ../
cpack -G "DEB"

For Redhat-based distributions:

1
2
3
4
5
6
git clone --recursive https://github.com/lnls-dig/halcs && \
cd halcs && \
mkdir -p build
cd build
cmake ../
cpack -G "RPM"

Then, just proceed normally with installing the packages on your system.

Using Make Build System

Here is the procedure to build the binary images from the source using make:

  1. Install make and gcc:
1
sudo apt-get install make gcc

for Debian-based systems.

1
sudo yum install make gcc-c++

for Fedora-based systems.

  1. Get the source code:
1
git clone --recursive https://github.com/lnls-dig/halcs
  1. Go to the source code directory:
1
cd halcs
  1. Build and install the code:
1
make && sudo make install

All in all, the full script to install HALCS with make is:

1
2
3
4
git clone --recursive https://github.com/lnls-dig/halcs && \
cd halcs && \
make && \
sudo make install

Alternatively you can use a script called ./compile.sh that gives you more flexibility in terms of compilation-time configurability. You should only use this method if the defaults are not sufficient for you use case:

  1. Install make and gcc:
1
sudo apt-get install make gcc

for Debian-based systems.

1
sudo yum install make gcc-c++

for Fedora-based systems.

  1. Get the source code:
1
git clone --recursive https://github.com/lnls-dig/halcs
  1. Go to the source code directory:
1
cd halcs
  1. Build and install the code:
1
./compile.sh -b afcv3_1 -a halcsd -e yes -l yes -d yes

The full procedure would be:

1
2
3
git clone --recursive https://github.com/lnls-dig/halcs && \
cd halcs && \
./compile.sh -b afcv3_1 -a halcsd -e yes -l yes -d yes

Installing HALCS client

Using CMake Build System

The recommended way to build the client libraries is to use cmake:

Build and install libraries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
TOP=$(pwd)
for lib in \
    errhand \
    convc \
    hutils \
    disptable \
    llio \
    halcsclient \
    acqclient \
    bpmclient \
    sdbfs \
    sdbutils; do

    (
        cd ${TOP}/libs/${lib} && \
        mkdir -p build && \
        cd build && \
        cmake ../ && \
        make && \
        sudo make install
    )
done

If you need to uninstall the libraries you can do with:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
TOP=$(pwd)
for lib in \
    sdbutils \
    sdbfs \
    bpmclient \
    acqclient \
    halcsclient \
    llio \
    disptable \
    hutils \
    convc \
    errhand; do

    (
        cd ${TOP}/libs/${lib} && \
        mkdir -p build && \
        cd build && \
        cmake ../ && \
        sudo make uninstall
    )
done

Using Make Build System

Another way to build the client libraries is to use make:

Build and install inner dependencies:

1
2
make deps
sudo make deps_install

And, then the client libraries themselves:

1
2
make libs
sudo make libs_install

If you need to uninstall the libraries do:

1
sudo make libs_uninstall

Installing HALCS examples

Change to the examples folder:

1
cd examples

Using CMake Build System

The recommended way to build the examples is to use cmake:

1
2
3
4
mkdir -p build
cd build
cmake ../
make

Using Make Build System

Another way to build the examples is to use make:

1
make

UDEV scripts

HALCS includes three udev scripts, two generic one that sets the device permissions to the appropriate ones (called 60-udev-fpga-rules and 80-udev-fpga-rules) and another customized udev script, in which you can automatically start a userspace application if a certain condition is detected (called 81-udev-fpga-rules). If this, an application will automatically start a given program when some ID is detected.

Typically the ID used is the Gateware Name represented by the SDB [5] property synthesis-name that is baked inside the FPGA Gateware.

[5]https://ohwr.org/project/fpga-config-space/wikis/home

To add your specific program to start when some ID is found, the run-fpga-program.sh (typically installed in /usr/local/share/halcs or /usr/share/halcs) script can be modified. Below, an excerpt of the script is shown with a possible modification to allow starting another program:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
...

for i in $(seq 1 "${#HALCS_IDXS[@]}"); do
    prog_inst=$((i-1));
    case "${GATEWARE_NAME}" in
        bpm-gw*)
            case "${FMC_NAMES[$prog_inst]}" in
                LNLS_FMC250M*)
                    START_PROGRAM="/usr/bin/systemctl --no-block start halcs-ioc@${HALCS_IDXS[$prog_inst]}.target"
                    ;;
                LNLS_FMC130M*)
                    START_PROGRAM="/usr/bin/systemctl --no-block start halcs-ioc@${HALCS_IDXS[$prog_inst]}.target"
                    ;;
                *)
                    echo "Unsupported Gateware Module: "${FPGA_FMC_NAME} >&2
                    exit 1
                    ;;
            esac
            ;;

        tim-receiver*)
            START_PROGRAM="/usr/bin/systemctl --no-block start halcs-ioc@${HALCS_IDXS[$prog_inst]}.target"
            ;;

        afc-tim*)
            # Only start IOCs for even-numbered instances, as there is no device for odd-numbered instances
            if [ $((prog_inst%2)) -eq 0 ]; then
                START_PROGRAM="/usr/bin/systemctl --no-block start tim-rx-ioc@${HALCS_IDXS[$prog_inst]}.service"
            else
                START_PROGRAM=""
            fi
            ;;

        pbpm-gw*)
            START_PROGRAM="/usr/bin/systemctl --no-block start halcs-ioc@${HALCS_IDXS[$prog_inst]}.target"
            ;;

        <ADD YOU GATEWARE NAME HERE>*)
            START_PROGRAM="<ADD YOUR START PROGRAM HERE>"
            ;;

        *)
            echo "Invalid Gateware: "${GATEWARE_NAME} >&2
            exit 2
            ;;
    esac

    eval ${START_PROGRAM}
done

...

Updating Dependencies

If you already have dependencies installed and wish to remote update to a specific release you can run the following snippet. Be advised that you would need to change the repository locations to match your environment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
NODES=()
NODES+=("<type the computer IP that you wish to update>")

for crate in "${NODES[@]}"; do
    SSHPASS=root sshpass -e ssh -o StrictHostKeyChecking=no \
    root@${crate} bash -s <<'EOF'
        set -x && \
        export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig && \
        DEP_DIR=/root/postinstall/apps/bpm-app && \
        libsodium_VER=1.0.8 && \
        libzmq_VER=v4.2.5 && \
        libczmq_VER=v4.0.2 && \
        malamute_VER=v1.6.1 && \
        cd ${DEP_DIR} && \
        for project in libsodium libzmq czmq; do
            PROJECT_VER=${project}_VER
            CONFIG_OPTS=()
            CONFIG_OPTS+=("CFLAGS=-Wno-format-truncation")
            CONFIG_OPTS+=("CPPFLAGS=-Wno-format-truncation")
            if [ $project == "libzmq" ]; then
                CONFIG_OPTS+=("--with-libsodium")
            fi

            cd $project && \
            git fetch --all && \
            git stash && \
            git checkout -f ${!PROJECT_VER} && \
            git reset --hard ${!PROJECT_VER} && \
            ./autogen.sh && \
            ./configure "${CONFIG_OPTS[@]}" && \
            make check && \
            make && \
            sudo make install && \
            sudo ldconfig && \
            cd ..

            # Check last command return status
            if [ $? -ne 0 ]; then
                echo "Could not compile/install project $project." >&2
                exit 1
            fi
        done

        cd ${DEP_DIR} && \
        for project in malamute; do
            PROJECT_VER=${project}_VER
            CONFIG_OPTS=()
            CONFIG_OPTS+=("--with-systemd-units")
            CONFIG_OPTS+=("--sysconfdir=/usr/etc")
            CONFIG_OPTS+=("--prefix=/usr")
            CONFIG_OPTS+=("CFLAGS=-Wno-format-truncation")
            CONFIG_OPTS+=("CPPFLAGS=-Wno-format-truncation")

            cd $project && \
            git fetch --all && \
            git stash && \
            git checkout -f ${!PROJECT_VER} && \
            git reset --hard ${!PROJECT_VER} && \
            ./autogen.sh && \
            ./configure "${CONFIG_OPTS[@]}" && \
            make check && \
            make && \
            sudo make install && \
            sudo ldconfig && \
            cd ..

            MALAMUTE_VERBOSE=0
            MALAMUTE_PLAIN_AUTH=
            MALAMUTE_AUTH_MECHANISM=null
            MALAMUTE_ENDPOINT='ipc:///tmp/malamute'
            MALAMUTE_CFG_FILE=/usr/etc/malamute/malamute.cfg
            # Install our custom Malamute config file
            sudo sed -i \
                -e "s|verbose\( *\)=.*|verbose\1= ${MALAMUTE_VERBOSE}|g" \
                -e "s|plain\( *\)=.*|plain\1= ${MALAMUTE_PLAIN_AUTH}|g" \
                -e "s|mechanism\( *\)=.*|mechanism\1= ${MALAMUTE_AUTH_MECHANISM}|g" \
                -e "s|tcp://\*:9999|${MALAMUTE_ENDPOINT}|g" \
                ${MALAMUTE_CFG_FILE}

            # Enable service
            sudo systemctl enable malamute || /bin/true
            sudo systemctl restart malamute || /bin/true

            # Check last command return status
            if [ $? -ne 0 ]; then
                echo "Could not compile/install project $project." >&2
                exit 1
            fi
        done
EOF
done

Updating HALCS

If you already have the software installed and wish to remote update to the latest release you can run the following snippet. Be advised that this is just an example and assumes specific paths and running applications:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
NODES=()
NODES+=("<type the computer IP that you wish to update>")

for crate in "${NODES[@]}"; do
    SSHPASS=root sshpass -e ssh -o StrictHostKeyChecking=no \
    root@${crate} bash -s <<'EOF'
        set -x && \
        DEP_DIR=/root/postinstall/apps/bpm-app && \
        PROJECT_VER=master && \
        cd ${DEP_DIR}/halcs && \
        git fetch --all && \
        git checkout -b stable-$(date +%Y%m%d-%H%M%S) && \
        git checkout ${!PROJECT_VER} && \
        git reset --hard ${!PROJECT_VER} && \
        cp /usr/local/etc/halcs/halcs.cfg /home/lnls-bpm/halcs.cfg.temp && \
        systemctl stop \
            halcs@{7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}.target && \
        cd ${DEP_DIR}/halcs && \
        mkdir -p build && \
        cd build && \
        cmake ../ && \
        make && \
        sudo make install && \
        mv /home/lnls-bpm/halcs.cfg.temp /usr/local/etc/halcs/halcs.cfg && \
        systemctl daemon-reload && \
        systemctl start \
            halcs-ioc@{7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24}.target
EOF
done

Source Code Organization

To be written

Dependencies

HALCS depends on the following libraries:

libsodium
Repository: https://github.com/jedisct1/libsodium/tree/1.0.8
Version: 1.0.8
zeromq
Repository: https://github.com/zeromq/libzmq/tree/v4.2.5
Version: v4.2.5
czmq
Repository: https://github.com/zeromq/czmq/tree/4.0.2
Version: 4.0.2
mlm
Repository: https://github.com/lnls-dig/malamute/tree/v1.6.1
Version: v1.6.1