6.1. Linux

6.1.1. OS optimizations

Linux itself is not real-time capable, so it is recommended to use it with the additional PREEMPT_RT patch.

The power management can disrupt cyclical processing, it is advisable to disable the CPUIDLE sub-system and CPUFREQ sub-system. The sub-systems can be disabled by changing the kernel command line parameters in the boot loader. On x86, x86_64 systems this is usually grub, on embedded devices with ARM, ARM64 is usually u-boot. It is also possible to build a custom kernel without these sub-systems.

Running a EC-Master application on a dedicated CPU core that is isolated from the Linux scheduler (ISOLCPUS) can provide additional stability.

6.1.1.1. CPUIDLE sub-system

Check if CPUFREQ sub-system is enabled:
ls /sys/devices/system/cpu/

If cpuidle appears in the list, it is enabled.

Disable CPUIDLE via the kernel command-line in grub:
linux  /boot/vmlinuz-4.19.0-16-rt-amd64 cpuidle.off=1

6.1.1.2. CPUFREQ sub-system

Check if CPUFREQ sub-system is enabled:
ls /sys/devices/system/cpu/

If cpufreq appears in the list, it is enabled.

Disable CPUFREQ sub-system via the kernel command-line grub:
linux  /boot/vmlinuz-4.19.0-16-rt-amd64 cpufreq.off=1

If CPUFREQ is not to be deactivated, the governor should be set to performance.

The currently active governor can be determined as follows:
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
The available governors with:
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_available_governors
To change governor use:
echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

6.1.1.3. ISOLCPUS

Isolate CPU core number 4 of a quad-core processor via the kernel command-line grub:
linux  /boot/vmlinuz-4.19.0-16-rt-amd64 isolcpus=3
Running EcMonitorDemo on the isolated CPU core by setting the CPU affinity -a:
./EcMonitorDemo -a 3

6.1.2. atemsys kernel module

To use Optimized Link Layers under Linux, the atemsys kernel module must be compiled and loaded. atemsys grants direct access to hardware to improve the performance.

All necessary scripts, source code and a detailed description of the installation can be found on https://github.com/acontis/atemsys. A ready-to-use Yocto recipe is also available on https://github.com/acontis/meta-acontis

6.1.2.1. atemsys as Device Tree Ethernet Driver

atemsys can also be used as a device tree driver to avoid certain conflicts between the link layer and the Linux kernel, e.g. power management, shared MDIO bus, etc..

A detailed guide on how to customize the device tree accordingly can also be found on https://github.com/acontis/atemsys. Example device tree modifications for different link layers/SoC can be found in https://github.com/acontis/atemsys/wiki.

Note

This is the preferred solution on all embedded devices with device tree support.

6.1.2.2. atemsys and PHY OS Driver

To use the PHY OS Driver, the acontis kernel module atemsys has to be included in the kernel device tree as an official driver for the Ethernet controller and doesn’t required any additional configuration at the application level. As a result atemsys can interact with Linux drivers.

6.1.4. Docker

It is possible to operate EC-Master within a Docker container with realtime priority. The atemsys kernel module should be installed on the host in order to operate the container with the lowest possible capabilities and privileges.

The following additional settings, permissions for docker run are required:

Add atemsys device to container
--device=/dev/atemsys:/dev/atemsys
Allow max realtime priority
--ulimit rtprio=99
Add capability to set priority an lock memory
--cap-add=sys_nice
--cap-add=ipc_lock
Publish RAS server port 6000
-p 6000:6000

6.1.5. Setting up and running EcMonitorDemo

  1. Unbind Link Layer instance, e.g.

    echo 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind

  2. Load atemsys kernel module

    insmod atemsys.ko

  3. Copy files from EC-Master package /bin and a eni.xml to directory e.g. /tmp.

  4. Adjust LD_LIBRARY_PATH search locations for Optimized Link Layers if necessary, e.g.

    export LD_LIBRARY_PATH=/tmp:$LD_LIBRARY_PATH

  5. Run EcMonitorDemo

    cd /tmp
./EcMonitorDemo -f eni.xml -i8254x 1 1 -perf

See also

Running EcMonitorDemo

6.1.5.1. Run in Docker container

  1. Unbind Link Layer instance and load atemsys on the host.

  2. Create a directory on the host (e.g. ~/docker) and copy files from EC-Master package /bin and eni.xml into this directory.

  3. Start bash console in container

    sudo docker run -it \
    --name atem_container \
    --device=/dev/atemsys:/dev/atemsys \
    --ulimit rtprio=99 \
    --cap-add=sys_nice --cap-add=ipc_lock \
    -v ~/docker:/home/docker \
    -p 6000:6000 \
    ubuntu bash

    Command line arguments:

    • -it Allocate a pseudo-TTY and run container

    • --name atem_container Container name

    • --device=/dev/atemsys:/dev/atemsys Add atemsys device to container

    • --ulimit rtprio=99 Allow max realtime priority

    • --cap-add=sys_nice Add Linux capability to set priority

    • --cap-add=ipc_lock Add Linux capability to lock memory

    • -v ~/docker:/home/docker Mount previously create directory to container

    • -p 6000:6000 Publish RAS server port 6000

    • ubuntu bash Use Docker image ubuntu and start bash

  4. Run EcMonitorDemo in container

    cd /home/docker
export LD_LIBRARY_PATH=.
./EcMonitorDemo -f eni.xml -i8254x 2 1 -perf

6.1.6. OS Compiler settings

Besides the general settings from Compiling the EcMonitorDemo the following settings are necessary to build the example application for Linux

Extra include paths
<InstallPath>/SDK/INC/Linux
<InstallPath>/Examples/Common/Linux
Extra source paths
<InstallPath>/Examples/Common/Linux
<InstallPath>/Sources/OsLayer/Linux
Extra library paths to the main EtherCAT components
<InstallPath>/SDK/LIB/Linux/<Arch>
Extra libraries
pthread dl rt