1.4.2. Linux specific information

On Linux systems the runtime is a user space application. For realtime behavior the realtime-preempt patches from Ingo Molnar and Thomas Gleixner are needed. But the integration is transparent, so a standard vanilla kernel or a standard Linux distribution like e.g. debian also may be used.

For full functionality the runtime has to be started with root privileges. Starting it as a regular user is possible, but the following functionality will fail and this causes severe drawbacks. There might be the possibility to set specific capabilities (see manpage capabilities) or resource limits (see manpage setrlimit) to avoid this:

  • set realtime priority (SCHED_FIFO) for threads -> no realtime tasks possible

  • lock process memory via mlockall() -> realtime behavior might be bad

  • creating raw sockets -> ethernet based fieldbusses will not work

  • ifconfig up/down -> baudrate for CAN bus can’t be set

1.4.2.1. CAN bus

For CAN bus access you have to provide a script for setting the baudrate of the CAN bus. The default name is “rts_set_baud.sh” and it will be called “./rts_set_baud.sh <interfacename> <baudrate/1000>”. Usually this can be done by the “ip link” command and the implementation may look like this:

#!/bin/sh
BITRATE=`expr $2 \\* 1000`
ifconfig $1 down
echo ip link set $1 type can bitrate $BITRATE
ip link set $1 type can bitrate $BITRATE
ifconfig $1 up;

For further templates refer to the Platforms/Linux/Templates/rts_set_baud folder of your toolkit. Configuration options are documented in the CODESYS Help -> CmpSocketCanDrvItf.

1.4.2.2. Environment variables and command line parameters

Command line parameters:

Usage: codesyscontrol [OPTION]… [ConfigurationFile]
If [ConfigurationFile] isn’t specified, a file named CODESYSControl.cfg is expected to reside in the working directory of the runtime system
Valid options:
-h, –help display this help and exit
-v, –version display version information and exit
d[level], –debug print additonal debug output
-b, –daemon run in the background
–printlostcycles print debug output if a cycle in a realtime iec tasks is lost

Environment variables:

There are some environment variables to influence the behavior of the runtime.

PlcConfigFile=<path/filename>

use this file as configuration file. Path is optional. Only evaluated if the configuration file was not set as a command line parameter.

QWS_COMMANDLINE_PARAM

QT parameters to be passed to the implicitly generated QT Application (default: “-qws”).

QT_QPA_NO_SIGNAL_HANDLER=1

Disable Qt signal handling. Use if runtime does not exit cleanly when pressing Ctrl-C

Target visualization on top of X11 based QT only:

RTS_WINDOW_MAXIMIZED

not set: full screen mode(default) set(any value): maximized window

RTS_CURSER_VISIBLE=0|1

0: hide cursor 1: show cursor(default)

1.4.2.3. Task Mapping

For information about task priorities in the runtime refer to chapter 3.7. The runtime priorities are mapped to the Linux priorities according to this scheme:

runtime priority

Linux priority (default)

Corresponding IEC Task priority

Name

Value (default)

System Base

0

88 (SCHED_FIFO)

–

System End

31

57 (SCHED_FIFO)

–

RealTime Base

32

56 (SCHED_FIFO)

0 (highest realtime Prio)

RealTime Base + 15

47

41 (SCHED_FIFO)

15 (lowest realtime Prio)

RealTime Base + 16

48

0 (SCHED_OTHER)

16 (non realtime Prio)

RealTime End

63

0 (SCHED_OTHER)

31 (non realtime Prio)

High Base

>= 64

0 (SCHED_OTHER)

–
If the runtime priority is in the range SystemBase-RealtimeBase+15 the Linux scheduling policy is set to SCHED_FIFO and the priority is computed this way:
max_priority_os – <value of runtime priority>.
Otherwise it is set to SCHED_OTHER with priority 0.
The max_priority_os (default 88) may be set in the configuration file (SysTask->Linux.MaxOSPriority). Valid Values are 49 to 99.
So it is possible to change this mapping either by changing the values of the runtime priorities or by changing the value of the maximum of the used linux priorities. Both is described in the documentation of SysTaskItf.

1.4.2.4. Multicore

By default Linux is balancing the processes and threads across all available cores. To avoid this behavior on multicore systems, it is recommended to use the Linux tool “taskset”.

For example:

taskset -a 02 codesyscontrol /etc/CODESYSControl.cfg

Note

CODESYS doesn’t support the multicore processing on all systems. Please ask our support if you are unsure if your system supports this.

1.4.2.5. Filesystem layout

Based on the “Filesystem Hierarchy Standard”, we are recommending the following filesystem layout for CODESYS Runtime, running on Linux:

  • /etc – runtime configuration files (e.g. CODESYSControl.cfg)
    As some sections of the runtime configuration file are changed during runtime (e.g. [CmpApp]), you may want to split the file into a user writeable and a static one. If /etc is write protected, you may want to move the user writeable file to a writeable directory and link it to /etc.
    Also the license file 3S.dat, shall be placed under /etc. It can be mapped there with the following entry in the configuration file:
    [SysFile]
    FilePath.1=/etc/, 3S.dat
  • /var/opt/<package-name> - application specific files
    The application specific files can be mapped with a setting in the configuration file:
    [SysFile]
    FilePath=/var/opt/<package-name>/
    By default the working directory of the runtime will be used.
    This is normally the working directory of the runtime process / service
    Please be aware, that all files you put here can be accessed via CODESYS
    file transfer feature!
  • /opt/<package-name> - CODESYS Control binaries, scripts, etc…
    All binaries, scripts, etc. which are necessary to run CODESYS, should be placed under “/opt/<package-name>/”.

Note

See further documentation about filepaths and wildcard mechanism.

Note

Shared libraries, which are solely runtime dependent, should be placed under /opt/<package-name>, too. Otherwise they will be mixed up with system libraries.

In general it is recommended to use read-only mounted file-systems as far as possible. It is good to differentiate between three categories of files:

  1. Read-Only:
    The whole filesystem shall be read-only by default.
  2. Read/Write:
    All files, which are accessible by CODESYS have to be writeable and readable. Specifically this will be /var/opt/<package-name>, but might also be the whole /var folder.
  3. Temporary:
    Log files and those which don’t have to be stored across reboots, could be placed in a temporary filesystem (of type tempfs). Specifically this is important for /tmp.

1.4.2.6. Build static runtime

Every CODESYS Linux Toolkit contains a static library beside the CODESYS binary. This library archive can be used to statically build customized runtimes. For example:
gcc -o codesyscontrol main.c codesyscontrol.a *.3rdp.a -lc -lm -lpthread -ldl -lrt
In case of missing symbols including all objects from the codesyscontrol archive might be helpful.
gcc -o codesyscontrol main.c -Wl,--whole-archive codesyscontrol.a -Wl,--no-whole-archive *.3rdp.a -lc -lm -lpthread -ldl -lrt
Note: Do not include *.3rdp.a files on command line which are provided by dynamic shared libraries already.

To extend the runtime with more components, which are also statically linked, the list of static components from “profile.h” has to be extended.

Note

The use of the CODESYS Runtime as a shared object is not recommended, and no longer supported. Instead it is recommended to use the static library approach to link all runtime components together. If it is necessary to use the CODESYS Runtime as shared object, no dynamic components shall be used.

1.4.2.7. Getting started with your Linux delivery

  • extend functionality by own IEC library write an IEC function in an own IEC library to access “firmware”/C-functions in your own runtime component. see “How to write an external IEC function”

  • use event mechanism (CmpEventMgr) see “How to register to an event in an own component” Recommended Template: CmpTemplateEvent Example: CmpPlcWink

  • configure Retain mechanism (CmpRetain): see “How to configure Retains easyily with CmpRetainsMMap” Recommended Template and example: CmpRetainsMMap

  • write own IO driver: see “How to write a very simple IO driver” Recommended Template and example: “IoDrvVerySimple”