epics-base/documentation/RELEASE-7.0.3.1.md

Release Notes

This document describes the changes that were included in the release of EPICS noted below. Release entries are now provided in a separate document for each version in the EPICS 7 series, but all are combined into a single page for publishing on the EPICS website. Separate release documents are also included from the older Base 3.15 and 3.16 series.

EPICS Release 7.0.3.1

IMPORTANT NOTE: Some record types in this release will not be compatible with device support binaries compiled against earlier versions of those record types, because importing the record documentation from the EPICS Wiki as described below also modified the order of some of the fields in the record definitions. As long as all support modules and IOCs are rebuilt from source after updating them to use this release of EPICS Base, these changes should not have any affect.

logClient reliability

On supported targets (Linux, Mac, Windows) logClient will attempt to avoid dropping undelivered log messages when the connection to the log server is closed/reset.

Timers and delays use monotonic clock

Many internal timers and delay calculations use a monotonic clock epicsTimeGetMonotonic() instead of the realtime epicsTimeGetCurrent(). This is intended to make IOCs less susceptible to jumps in system time.

Iocsh on error ...

A new statement is added to enable IOC shell commands to signal error conditions, and for scripts to respond. This first is through the new function

    int iocshSetError(int err);

A script may be prefixed with eg. "on error break" to stop at the failed command.

    on error continue | break | wait [value] | halt

A suggested form for IOC shell commands is:

    static void doSomethingCallFunc(const iocshArgBuf *args)
    {
        iocshSetError(doSomething(...)); /* return 0 == success */
    }

Relocatable Builds

Allows built trees to be copied or moved without invalidating RPATH entries.

The LINKER_USE_RPATH Makefile variable (see configure/CONFIG_SITE) may be set to YES, NO, and a new third option ORIGIN. This is limited to targets using the ELF executable format (eg. Linux).

When LINKER_USE_RPATH=ORIGIN, the variable LINKER_ORIGIN_ROOT is set to one of the parents of the build directory. Any libraries being linked to which are found under this root will have a relative RPATH entry. Other libraries continue to result in absolute RPATH entries.

An effect of this might change a support library from being linked with -Wl,-rpath /build/epics-base/lib/linux-x86 to being linked with -Wl,-rpath \$ORIGIN/../../../epics-base/lib/linux-x86 if the support module directory is /build/mymodule and LINKER_ORIGIN_ROOT=/build.

The API functions epicsGetExecDir() and epicsGetExecName() are also added to osiFileName.h to provide runtime access to the directory or filename of the executable with which the process was started.

Decouple LINKER_USE_RPATH and STATIC_BUILD

Previously, setting STATIC_BUILD=NO implied LINKER_USE_RPATH=NO. This is no longer the case. Setting LINKER_USE_RPATH=YES will always emit RPATH entries. This was found to be helpful when linking against some 3rd party libraries which are only available as shared objects.

Channel Access Security: Check Hostname Against DNS

Host names given in a HAG entry of an IOC's Access Security Configuration File (ACF) have to date been compared against the hostname provided by the CA client at connection time, which may or may not be the actual name of that client. This allows rogue clients to pretend to be a different host, and the IOC would believe them.

An option is now available to cause an IOC to ask its operating system to look up the IP address of any hostnames listed in its ACF (which will normally be done using the DNS or the /etc/hosts file). The IOC will then compare the resulting IP address against the client's actual IP address when checking access permissions at connection time. This name resolution is performed at ACF file load time, which has a few consequences:

1. If the DNS is slow when the names are resolved this will delay the process of loading the ACF file.

2. If a host name cannot be resolved the IOC will proceed, but this host name will never be matched.

3. Any changes in the hostname to IP address mapping will not be picked up by the IOC unless and until the ACF file gets reloaded.

Optionally, IP addresses may be added instead of, or in addition to, host names in the ACF file.

This feature can be enabled before iocInit with

    var("asCheckClientIP",1)

or with the VxWorks target shell use

    asCheckClientIP = 1

New and modified epicsThread APIs

epicsThreadCreateOpt()

A new routine epicsThreadCreateOpt() is an alternative to epicsThreadCreate() which takes some arguments via a structure (struct epicsThreadOpts) to allow for future extensions.

    typedef struct epicsThreadOpts {
        unsigned int priority;
        unsigned int stackSize;
        unsigned int joinable;
    } epicsThreadOpts;
    #define EPICS_THREAD_OPTS_INIT { \
        epicsThreadPriorityLow, epicsThreadStackMedium, 0}
     epicsThreadId epicsThreadCreateOpt(const char * name,
        EPICSTHREADFUNC funptr, void * parm, const epicsThreadOpts *opts);

The final opts parameter may be NULL to use the default values of thread priority (low) and stack size (medium). Callers wishing to provide alternative settings for these thread options or to create a joinable thread (see below) should create and pass in an epicsThreadOpts structure as shown below. Always initialize one of these structures using the EPICS_THREAD_OPTS_INIT macro to ensure that any additional fields that get added in the future are set to their default values.

    void startitup(void) {
        epicsThreadOpts opts = EPICS_THREAD_OPTS_INIT;
        epicsThreadId tid;

        opts.priority = epicsThreadPriorityMedium;
        tid = epicsThreadCreateOpt("my thread", &threadMain, NULL, &opts);
    }

C or C++ Code that also needs to build on earlier versions of Base can use #ifdef EPICS_THREAD_OPTS_INIT to determine whether the epicsThreadCreateOpt() API is available on this Base version.

Thread stack sizes

The stackSize member of the epicsThreadOpts structure and the equivalent parameters to the epicsThreadCreate() and epicsThreadMustCreate() routines can now be passed either one of the epicsThreadStackSizeClass enum values or a value returned from the epicsThreadGetStackSize() routine.

epicsThreadMustJoin()

If the new joinable flag of an epicsThreadOpts structure is non-zero (the default value is zero), the new API routine epicsThreadMustJoin() must be called with the thread's epicsThreadId when/after the thread exits, to free up thread resources. This function will block until the thread's main function has returned, allowing the parent to wait for its child thread. The child's epicsThreadId will no longer be valid and should not be used after the epicsThreadMustJoin() routine returns.

A thread that was originally created with its joinable flag set may itself call epicsThreadMustJoin(), passing in its own epicsThreadId. This marks the thread as no longer being joinable, so it will then free the thread resources itself when its main function returns. The epicsThreadId of a thread that is not joinable gets invalidated as soon as its main function returns.

Non-VME RTEMS targets now define pdevLibVME

Previously IOC executables that made calls to devLib routines would fail to link when built for some non-VME based RTEMS targets, which would have to be explicitly filtered out by sites that build Base for those targets. This fix makes that no longer necessary, all RTEMS targets should now link although the IOC won't be able to be used with the VME I/O on those systems (that we don't have VMEbus I/O support for in libCom).