Converting an EPICS R3.13 application to R3.14.4


This document describes how to convert a R3.13 vxWorks application so that it builds with release R3.14.4.  It describes procedures such that:

Gnumake clean uninstall

First do a gnumake clean uninstall in the application's root directory to remove all files created by earlier builds.

Create a new R3.14 application

We will remove junkApp later.

mkdir <top>
cd <top>
<full path to 3.14 base>/bin/<host_arch>/makeBaseApp.pl -t example junk

Copy all *App and iocBoot directories and files to the new <top> directory

cd <oldtop> 
find *App iocBoot -print | cpio -pvmd <fullpath name to new top>

Modify <top>/configure/RELEASE

Copy definitions of external modules excluding EPICS_BASE and TEMPLATES_TOP from old application RELEASE file.
If sequence programs (*.st or *.stt files) exist in your application, add the SNCSEQ location definition for the R3.14 seq external module

SNCSEQ =<full path to seq module top>

The R3.14 seq module must exist and be built with EPICS base R3.14.4

Modify the Makefiles in <top>/*App directories.

Change "include $(TOP)/config/CONFIG_APP" to "include $(TOP)/configure/CONFIG"

Change " include $(TOP)/config/RULES_DIRS" to  "include $(TOP)/configure/RULES_DIRS"

Modify the Makefiles in <top>/*App/*Db directories.

Remove existing Makefile
Rename Makefile.Host to Makefile
Modify Makefile as follows:

Change "TOP=../../.." to "TOP=../.."

Change    "include $(TOP)/config/CONFIG_APP" to "include $(TOP)/configure/CONFIG"

Change "include $(TOP)/config/RULES.Db" to "include $(TOP)/configure/RULES"

Place all definitions between the include lines.

Place any rules after the last include line.

Modify the Makefiles in <top>/*App/src directories.

This is the hardest step. The definitions in Makefile.Host and Makefile.Vx must be manually converted to the new configure definitions.

First replace Makefile with the Makefile from junkApp/src.

rm Makefile
cp ../../junkApp/src/Makefile .

We can remove the junkApp now.

/bin/rm -fr ../../junkApp

This new Make file has comments explaining how to build the various host and ioc products. Lets consider some examples

After these changes are made the following files are no longer needed: baseLIBOBS, Makefile.Host, and Makefile.Vx

File base.dbd no longer needed

You now can add the line include "base.dbd" to your <appname>Include.dbd file and remove the file <name>App/src/base.dbd from your src directory. The base.dbd from base/dbd will be included. However, if you only want a subset of record definitions from base you should keep your base.dbd file.

Record support

Add the following line after all existing #includes
#include "epicsExport.h"
The structure rset is now a typedef so change
struct rset RSET={ ...
to
rset RSET={ ...
and add the following line after the "rset <recordname>RSET=" definition.
epicsExportAddress(rset,xxxRSET);

Device support

Add the following line after all existing #includes
#include "epicsExport.h"
and add the following line after the dset dev<devname> definition
epicsExportAddress(dset,dev<devname>);

Driver support

Add the following line after all existing #includes
#include "epicsExport.h"
and add the following line after the drvet dev<devname> definition
epicsExportAddress(drvet,drv<devname>);

Registration code changed

Registration code for application specific functions, e.g. subroutine record init and process functions, has been changed as follows

1) Include the registration support header files:

#include "dbDefs.h"
#include "registryFunction.h"
2) Include the export definitions header file after including all other header files:
#include "epicsExport.h"
3) Make the application specific functions static functions, e.g.
static long mySubInit(subRecord *precord,processMethod process)
static long mySubProcess(subRecord *precord)
4) Define a registryFunctionRef array of the application specific functions to be registered, e.g.
static registryFunctionRef mySubRef[] = {
    {"mySubInit",(REGISTRYFUNCTION)mySubInit},
    {"mySubProcess",(REGISTRYFUNCTION)mySubProcess}
};
5) Add a new function to do the registration of the registryFunctionRef array elements, e.g.
void mySub(void)
{
    registryFunctionRefAdd(mySubRef,NELEMENTS(mySubRef));
}
6) Call the epicsExportRegistrar with the new registration function: e.g.
epicsExportRegistrar(mySub);
7) Remove the existing function lines in <appname>Include.dbd: e.g. remove
function("mySubInit")
function("mySubProcess")
8) Add a registrar statement to <name>Include.dbd with the new registration function as parameter: e.g. add
registrar("mySub")

Modify the Makefiles in <top>/iocBoot directory.

Change " include $(TOP)/config/CONFIG_APP" to "include $(TOP)/configure/CONFIG"

Remove the line "DIRS += $(wildcard *ioc*"

Change "include $(TOP)/config/RULES.iocBoot" to "include $(TOP)/configure/RULES.iocBoot"

Modify the Makefiles in <top>/iocBoot/ioc* directories.

Change "include $(TOP)/config/CONFIG_APP" to "include $(TOP)/configure/CONFIG"

Change

include ARCH = <old arch specification e.g. mv167>

to

"include ARCH = <new arch specification e.g. vxWorks-68040>"

Change "include $(TOP)/config/RULES.ioc" to "include $(TOP)/configure/RULES.ioc"

If it exists remove the line

buildInstall: cdCommands

Add the line

TARGETS = cdCommands

before the include for RULES.ioc line.

Modify st.cmd in <top>/iocBoot/ioc* directories.

Remove the lines

ld < seq
ld < iocCore

Change "ld < <libname>Lib" to "ld < <libname>.munch"

Change "cd appbin" to "cd topbin"

Change the statement:

dbLoadDatabase("../../dbd/exampleApp.dbd")

to
dbLoadDatabase("../../dbd/<name>.dbd")
<name>_registerRecordDeviceDriver(pdbbase)

where <name> is replaced with the name of your dbd file.

recGbl calls

If any source file makes calls to recGbl routines make sure it has "#include "recGbl.h". If it doesn't the compiler will issue warning messages and the ioc may issue the message: "undefined symbol: _recGblSetSevr".

Record support changes

The steppermotor, scan, and pid records are no longer in base.  If these records are not used in your application, comment out references to them in base.dbd. If these record types are used at your site, they  should be downloaded and built with base R3.14 by your EPICS administrator. To update the R3.14 location of these record types in your application you must  add appropriate module definitions to your application's config/RELEASE file and add LIBOBJS definitions to the src Makefile.

For example add

         PID=<full path to modules directory>/pid

to config/RELEASE and add

LIBOBJS += $(PID_BIN)/pidRecord.o

to your application src/Makefile.

You should consider changing any existing old steppermotor records to the new EPICS  motor record  module supported by Beamline Controls and Data Acquisition at APS.

RecDynLink.o and devPtSoft changes

recDynLink.o and devPtSoft.o are no longer in EPICS base and now exist as separate EPICS modules.You must now add the appropriate module full path definitions to your application config/RELEASE file, and change LIBOBJS location definition $(EPICS_BASE_BIN) to the module definition bin directory in your application src directory files.  See "Hardware support changes" below for instructions.

Hardware support changes

All hardware support (dev, drv and dbd files) except soft support has been unbundled from base R3.14. This support includes the files symb.dbd, drvHp1404a.o, drvEpvxiMsg.o, and drvEpvxi.o. If these are not used by your application, comment out references to them in base.dbd.

Hardware support now exists as separate EPICS modules. The hardware support for your site should be downloaded and built with base R3.14 by your EPICS administrator. You must now add the appropriate module full path definitions to your application config/RELEASE file, and change LIBOBJS location from $(EPICS_BASE_BIN) to the module  bin directory in your application src directory files.

For example, remove

         LIBOBJS+=$(EPICS_BASE_BIN)/symb

from baseLIBOBJS and add

         LIBOBJS+=$(SYMB_BIN)/symb

to your application src/Makefile,
and add the line

SYMB=<full path definition for the built module SYMB>

into your application config/RELEASE file .

dbLoadtemplate tool changes

The host tool dbLoadTemplate has been replace by a new EPICS extension, msi, which should be downloaded and built with base R3.14 by your EPICS administrator. dbLoadTemplate is still supported on iocs.  If, in your application, db files are created from template and substitution files you should  add the definition

MSI=<full path name to msi executable>

to your application config/RELEASE file.