Scope of this Document

This documentation covers the C API and the iocShell commands of the EPICS Multi-Core Utilities.

Introduction

The EPICS Multi-Core Utilities library contains tools that allow tweaking of real-time parameters for EPICS IOC threads running on multi-core processors under the Linux operating system.

These tools are intended to set up multi-core IOCs for fast controllers, by:

Confining either parts or the complete EPICS IOC onto a subset of the available cores, allowing hard real-time applications and threads to run on dedicated cores.
Changing priorities of callback, driver or communication threads with respect to database processing.
Selecting real-time scheduling policy (FIFO or Round-Robin) for selected threads.
Locking the IOC process virtual memory into RAM to avoid swapping.

Advanced Thread Show Routines

An extended version of the epicsThreadShow() command, showing scheduling policy and CPU affinity in addition to the usual output.

Details can be found in the documentation for module Real-Time threadShow Routines.

Rule Based Real-Time Property Manipulation

A module allowing to specify rules, which consist of a regular expression to match the thread name against, and a set of commands that allow to specify the real-time properties of a thread.

Whenever the EPICS IOC starts a thread, its name is matched against all existing rules, and for matching rules the commands are applied.

Details can be found in the documentation for module Rule-Based Thread Properties.

Warning: The default priorities of the EPICS IOC threads are well-chosen. They have been proven to ensure reliable IOC operation and communication, in many installations, under a variety of circumstances.
Manipulating the real-time properties, especially scheduling policies and priorities, may have unwanted side effects. Use this feature sparingly, and test well.

Memory Locking

A module allowing to lock the IOC process virtual memory into RAM. This makes sure that no swapping occurs, and thus avoids page faults which would introduce latency and lead to indeterministic timing.

Details can be found in the documentation for module Memory Locking.

Sources

The sources are on GitHub at https://github.com/epics-modules/MCoreUtils

They can be checked out using

git clone https://github.com/epics-modules/MCoreUtils.git

Releases can be found on GitHub (see above) or at http://sourceforge.net/projects/epics/files/mcoreutils/

Requirements

Linux operating system
EPICS BASE 3.15 (3.15.1 or later)

Installation

Unpack the distribution tar or check out the source tree.
Run make
To generate a minimal example IOC, run make -C example

Usage

To use the Multi-Core Utilities in an IOC application tree, you have to add a definition to .../configure/RELEASE that points to the location of the mcoreutils module.

In the directory that builds your IOC binary, the Makefile has to make sure the IOC is only built for Linux. Then add the dbd file and the Library, e.g.:

...
PROD_IOC_Linux = mcutest
...
mcutest_DBD += mcoreutils.dbd
...
mcutest_LIBS += mcoreutils
...

That's it. Enjoy!