\\newpage # Linux ## 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](#cpuidle-sub-system) and [CPUFREQ sub-system](#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 an EC-Simulator application on a dedicated CPU core that is isolated from the Linux scheduler ([ISOLCPUS](#isolcpus)) can provide additional stability. ### CPUIDLE sub-system Check if CPUFREQ sub-system is enabled: : ```console $ ls /sys/devices/system/cpu/ ``` If `cpuidle` appears in the list, it is enabled. Disable CPUIDLE via the kernel command-line in GRUB: : ```default linux /boot/vmlinuz-4.19.0-16-rt-amd64 cpuidle.off=1 ``` ### CPUFREQ sub-system Check if CPUFREQ sub-system is enabled: : ```console $ ls /sys/devices/system/cpu/ ``` If `cpufreq` appears in the list, it is enabled. Disable CPUFREQ sub-system via the kernel command-line GRUB: : ```default 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: : ```console $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor ``` The available governors with: : ```console $ cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_available_governors ``` To change governor use: : ```console $ echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor ``` ### ISOLCPUS Isolate CPU core number 4 of a quad-core processor via the kernel command-line GRUB: : ```default linux /boot/vmlinuz-4.19.0-16-rt-amd64 isolcpus=3 ``` `isolcpus` alone removes scheduler tasks from selected CPUs, but does not prevent timer interrupts, RCU callbacks, or network adapter IRQs. To fully isolate a CPU for real-time workloads, `nohz_full`, `rcu_nocbs`, and `irqaffinity` should be used together to eliminate kernel noise and ensure deterministic execution. Enhanced isolation of CPU core 4 via the kernel command-line GRUB: : ```default linux /boot/vmlinuz-4.19.0-16-rt-amd64 isolcpus=3 nohz_full=3 rcu_nocbs=3 rcu_nocb_poll irqaffinity=0-2 ``` Running EcSimulatorHilDemo on the isolated CPU core by setting the CPU affinity `-a`: : ```console $ ./EcSimulatorHilDemo -a 3 ``` ## atemsys kernel module To use Real-time Ethernet Drivers 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](https://github.com/acontis/atemsys). A ready-to-use Yocto recipe is also available on [https://github.com/acontis/meta-acontis](https://github.com/acontis/meta-acontis) ![EC-Master architecture diagram for Linux showing the atemsys kernel module providing direct hardware access for Real-time Ethernet Drivers](../../OsLayer/Media/ec-masterarchlinux.png) ### atemsys as Device Tree Ethernet Driver atemsys can also be used as a device tree driver to avoid certain conflicts between the Real-time Ethernet Driver 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](https://github.com/acontis/atemsys). Example device tree modifications for different Real-time Ethernet Drivers/SoC can be found in [https://github.com/acontis/atemsys/wiki](https://github.com/acontis/atemsys/wiki). #### NOTE This is the preferred solution on all embedded devices with device tree support. ### 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 require any additional configuration at the application level. As a result atemsys can interact with Linux drivers. ## Unbind Ethernet Driver instance Ethernet Driver instances used by Real-time Ethernet Drivers may not be bound by kernel driver modules! Unbind can be done by unloading the kernel driver module, via the unbind interface of the driver or by modifying the device tree. ### Unbind from kernel driver The following command unbinds an instance without unloading the kernel driver module: **PCI** ```console $ echo "" > /sys/bus/pci/drivers//unbind ``` Example: ```console $ echo "0000:00:19.0" > /sys/bus/pci/drivers/e1000e/unbind ``` This call requires the PCI bus, device, function codes (in the above example it is 0000:00:19.0). The codes can be found using Linux commands like, for example: ```console $ ls /sys/bus/pci/drivers/e1000e ``` **SoC** ```console $ echo "" > /sys/bus/platform/drivers//unbind ``` Example: ```console $ echo "2188000.ethernet" > /sys/bus/platform/drivers/fec/unbind ``` ### Unload kernel driver Not all drivers allow unbinding of network interfaces. If unbinding is not supported the corresponding Linux kernel driver must not be loaded. The following command lists the loaded kernel modules that may conflict with Real-time Ethernet Driver: ```console $ lsmod | egrep "" ``` Example: ```console $ lsmod | egrep "e1000|e1000e|igb" ``` PCI/PCIe: The command lspci -v shows which driver is assigned to which network card, e.g.: ```console $ lspci -v ``` ```console ... 11:0a.0 Ethernet controller: Intel Corporation 82541PI Gigabit Ethernet Controller (rev 05) ... Kernel driver in use: e1000e ``` Modules can be prevented from loading with the following commands: ```console $ echo blacklist | sudo tee -a /etc/modprobe.d/blacklist.conf $ update-initramfs -k all -u $ sudo reboot ``` The following table shows the Kernel modules related to the Real-time Ethernet Driver: | Chip | Real-time Ethernet Driver | Kernel driver(s) | Remarks | |-------------------------------------|-----------------------------|--------------------|----------------------| | Broadcom Genet | emllBcmGenet | genet | Unbind not supported | | Beckhoff CCAT | emllCCAT | ec_bhf | | | CPSW | emllCPSW | ti_cpsw | | | Generic | emllDpdk | | | | DesignWare 3504 | emllDW3504 | stmmac | | | | emllEG20T | | | | Freescale TSEC/eTSEC v1/2 | emllETSEC | gianfar_driver | | | Freescale FEC and ENET controller | emllFslFec | fec, fec_ptp | | | Cadence GEM/MACB | emllGEM | gem, macb | | | Intel Pro/1000 | emllI8254x | igb, e1000, e1000e | | | Intel Pro/1000 | emllIntelGbe | igb, e1000, e1000e | | | Intel Pro/100 | emllI8255x | e100 | | | ICSS | emllICSS | prueth,pruss | Unbind not supported | | RDC R6040 | emllR6040 | | | | Realtek RTL8139 | emllRTL8139 | 8139too, 8139cp | | | Realtek RTL8169 / RTL8111 / RTL8168 | emllRTL8169 | r8169 | Unbind not supported | | SuperH | emllSHEth | sh_eth | Unbind not supported | | Generic | emllSockRaw | | | | Generic | emllSockXdp | | | ## Docker It is possible to operate EC-Simulator 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 : ```default --device=/dev/atemsys:/dev/atemsys ``` Allow max realtime priority : ```default --ulimit rtprio=99 ``` Add capability to set priority an lock memory : ```default --cap-add=sys_nice --cap-add=ipc_lock ``` Publish RAS server port 6000 : ```default -p 6000:6000 ``` ## OS Compiler settings Besides the general settings from [OS Compiler settings](architecture_sdk.html.md#compile-ecdemo) the following settings are necessary to build the example application for Linux Possible ARCHs (see ATECAT_ARCHSTR in `SDK/INC/Linux/EcOsPlatform.h`): : - aarch64 (ARM 64Bit) - armv7-vfp-eabihf (ARM 32Bit) - PPC (PPC 32Bit with “-te500v2”) - riscv64 (RISC-V 64Bit) - x64 (x86 64Bit) - x86 (x86 32Bit)
An ARM VFP system returns success on : ```console $ readelf -A /proc/self/exe | grep Tag_ABI_VFP_args ``` Extra include paths : ```default /Examples/Common/Linux /SDK/INC/Linux ``` Extra source paths : ```default /Examples/Common/Linux /Sources/OsLayer/Linux ``` Extra library paths to the main EtherCAT® components : ```default /SDK/LIB/Linux/ ``` Extra libraries (in this order) : ```default EcSimulatorRasServer EcSimulator pthread dl rt ``` ## Build using cmake on Linux Example usage to build Linux x64 Debug with cmake: ```console $ cmake -DEC_OS=Linux -DEC_ARCH=x64 $ cmake --build . ``` ## Cross-platform development under Windows The following steps describe how to develop Linux cross-platform developing on Windows for Linux: `-DEC_OS=Windows -DEC_ARCH=x64` 1. **Install MinGW** : - Download the latest version of MinGW from the MinGW official website [https://osdn.net/projects/mingw/](https://osdn.net/projects/mingw/) - Install the mingw-get-setup.exe tool to C:\\MinGW - Select the ‘’Basic Setup’’ - Apply changes 2. **Install a cross platform toolchain** : - Download a cross-platform toolchain from e.g. the Linaro release storage server [https://releases.linaro.org/components/toolchain/gcc-linaro/](https://releases.linaro.org/components/toolchain/gcc-linaro/) - Unpack it to C:\\MinGW\\opt 3. **Build using cmake on Linux** Example usage to build for Linux x64 Debug on Windows with cmake and ninja: ```console $ cmake -DEC_OS=Linux -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug . $ cmake --build . ``` 4. **Build for LxWin using cmake on Linux** Example usage to build EcMasterDemo for Linux x64 Debug on Windows with cmake and ninja: ```doscon Workspace/LxWin/cmake/x64/Debug> cmake.exe -G Ninja ../../../../.. -DCMAKE_TOOLCHAIN_FILE=../../../../Linux/Toolchain.cmake -DEC_OS=LxWin -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug Workspace/LxWin/cmake/x64/Debug> ninja.exe EcMasterDemo ``` 5. **Cross build using cmake for Linux on Windows** Example usage to build EcMasterDemo for Linux x64 Debug on Windows with cmake and ninja: ```doscon Workspace/Linux/cmake/x64/Debug> cmake.exe -G Ninja ../../../../.. -DCMAKE_TOOLCHAIN_FILE=../../../Toolchain.cmake -DEC_OS=Linux -DEC_ARCH=x64 -DCMAKE_BUILD_TYPE=Debug Workspace/Linux/cmake/x64/Debug> ninja.exe EcMasterDemo ``` 6. **Cross build using Eclipse CDT on Windows** : - Download and install the latest version of Eclipse CDT from the Eclipse official website [https://projects.eclipse.org/projects/tools.cdt](https://projects.eclipse.org/projects/tools.cdt) - Create a start batch file for eclipse
```batch set PATH=C:\MinGW\bin;C:\MinGW\msys\1.0\bin;%LINUX_CROSS_GCC_ARM_PATH%;%PATH% set LINUX_CROSS_GCC_ARM_PATH=C:\MinGW\opt\gcc-linaro-7.3.1-2018.05-i686-mingw32_aarch64-linux-gnu\bin set CFLAGS=-IC:\MinGW\opt\gcc-linaro-7.3.1-2018.05-i686-mingw32_aarch64-linux-gnu\aarch64-linux-gnu\libc\usr\include set CROSS_COMPILE=aarch64-linux-gnu- set ARCH=aarch64 eclipse.exe ```