438 lines
13 KiB
HTML
438 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
||
"http://www.w3.org/TR/html4/loose.dtd">
|
||
<html>
|
||
<head>
|
||
<title></title>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||
<meta name="Author" content="jba">
|
||
</head>
|
||
|
||
<body>
|
||
|
||
<center>
|
||
<h2>Converting an EPICS R3.13 application to R3.14.4</h2>
|
||
</center>
|
||
|
||
<p><br>
|
||
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:</p>
|
||
<ul>
|
||
<li>The application uses the configure rules which are new to R3.14.</li>
|
||
</ul>
|
||
<ul>
|
||
<li>The OSI (Operating System Independent) features of R3.14 are available,
|
||
i.e. iocCore products can be build for vxWorks as well as other
|
||
platforms, e.g. solaris and linux.</li>
|
||
</ul>
|
||
|
||
<h3>Gnumake clean uninstall</h3>
|
||
|
||
<p>First do a gnumake clean uninstall in the application's root directory to
|
||
remove all files created by earlier builds.</p>
|
||
|
||
<h3>Create a new R3.14 application</h3>
|
||
<p>We will remove junkApp later.</p>
|
||
<pre>mkdir <top>
|
||
cd <top>
|
||
<full path to 3.14 base>/bin/<host_arch>/makeBaseApp.pl -t example junk
|
||
</pre>
|
||
|
||
<h3>Copy all *App and iocBoot directories and files to the new <top>
|
||
directory</h3>
|
||
<pre>cd <oldtop>
|
||
find *App iocBoot -print | cpio -pvmd <fullpath name to new top></pre>
|
||
|
||
<h3>Modify <top>/configure/RELEASE</h3>
|
||
|
||
<p>Copy definitions of external modules excluding EPICS_BASE and
|
||
TEMPLATES_TOP from old application RELEASE file. <br>
|
||
If sequence programs (*.st or *.stt files) exist in your application, add the
|
||
SNCSEQ location definition for the R3.14 seq external module</p>
|
||
|
||
<p><tt>SNCSEQ =<full path to seq module top></tt></p>
|
||
The R3.14 seq module must exist and be built with EPICS base R3.14.4
|
||
|
||
<h3>Modify the Makefiles in <top>/*App directories.</h3>
|
||
|
||
<p>Change <tt>"include $(TOP)/config/CONFIG_APP"</tt> to <tt>"include
|
||
$(TOP)/configure/CONFIG"</tt></p>
|
||
|
||
<p>Change " i<tt>nclude $(TOP)/config/RULES_DIRS</tt>" to "<tt>include
|
||
$(TOP)/configure/RULES_DIRS"</tt></p>
|
||
|
||
<h3>Modify the Makefiles in <top>/*App/*Db directories.</h3>
|
||
|
||
<p>Remove existing Makefile <br>
|
||
Rename Makefile.Host to Makefile <br>
|
||
Modify Makefile as follows:</p>
|
||
|
||
<p>Change "<tt>TOP=../../.."</tt> to "<tt>TOP=../.."</tt></p>
|
||
|
||
<p>Change "i<tt>nclude $(TOP)/config/CONFIG_APP</tt>" to "<tt>include
|
||
$(TOP)/configure/CONFIG"</tt></p>
|
||
|
||
<p>Change "<tt>include $(TOP)/config/RULES.Db" </tt>to <tt>"include
|
||
$(TOP)/configure/RULES"</tt></p>
|
||
|
||
<p>Place all definitions between the include lines.</p>
|
||
|
||
<p>Place any rules after the last include line.</p>
|
||
|
||
<h3>Modify the Makefiles in <top>/*App/src directories.</h3>
|
||
|
||
<p>This is the hardest step. The definitions in Makefile.Host and Makefile.Vx
|
||
must be manually converted to the new configure definitions.</p>
|
||
|
||
<p>First replace Makefile with the Makefile from junkApp/src.</p>
|
||
<pre>rm Makefile
|
||
cp ../../junkApp/src/Makefile .</pre>
|
||
|
||
<p>We can remove the junkApp now.</p>
|
||
<pre>/bin/rm -fr ../../junkApp</pre>
|
||
|
||
<p>This new Make file has comments explaining how to build the various host
|
||
and ioc products. Lets consider some examples</p>
|
||
<ul>
|
||
<li>Host programs
|
||
<p>Makefile.Host contains definitions like:</p>
|
||
<pre>PROD += caExample
|
||
caExample_SRCS += caExample.c
|
||
PROD_LIBS += ca Db Com
|
||
ca_DIR = $(EPICS_BASE_LIB)
|
||
Db_DIR = $(EPICS_BASE_LIB)
|
||
Com_DIR = $(EPICS_BASE_LIB)
|
||
</pre>
|
||
<p>In Makefile these are:</p>
|
||
<pre>PROD_HOST += caExample
|
||
caExample_SRCS += caExample.c
|
||
caExample_LIBS += $(EPICS_BASE_HOST_LIBS)
|
||
</pre>
|
||
</li>
|
||
<li>Record Support - generate xxxRecord.h file
|
||
<p>Makefile.Host (or perhaps Makefile.Vx) contains:</p>
|
||
<pre>RECTYPES += xxxRecord.h
|
||
</pre>
|
||
<p>In Makefile this is:</p>
|
||
<pre>DBDINC += xxxRecord
|
||
</pre>
|
||
</li>
|
||
<li>Generating the .dbd file for all record/device/driver support
|
||
<p>Makefile.Host (or perhaps Makefile.Vx) contains:</p>
|
||
<pre>DBDEXPAND = exampleInclude.dbd
|
||
DBDNAME = exampleApp.dbd
|
||
</pre>
|
||
<p>In Makefile this is:</p>
|
||
<pre>DBD += example.dbd
|
||
</pre>
|
||
<p>NOTES: Change exampleApp.dbd to example.dbd in all st.cmd files. Also
|
||
this definition assumes that file exampleInclude.dbd exists.</p>
|
||
</li>
|
||
<li>Create the ioc application:
|
||
<p>Makefile.Vx contains statements like:</p>
|
||
<pre>SRCS.c += ../xxxRecord.c
|
||
SRCS.c += ../devXxxSoft.c
|
||
|
||
LIBOBJS += xxxRecord.o
|
||
LIBOBJS += devXxxSoft.o
|
||
LIBOBJS += sncExample.o
|
||
|
||
include ../baseLIBOBJS
|
||
|
||
LIBNAME = exampleLib
|
||
INSTALLS += iocCore seq
|
||
</pre>
|
||
<p>In Makefile these become:</p>
|
||
<pre>
|
||
LIBRARY_vxWorks += exampleIoc
|
||
exampleIoc_SRCS += xxxRecord.c
|
||
exampleIoc_SRCS += devXxxSoft.c
|
||
exampleIoc_LIBS += $(EPICS_BASE_IOC_LIBS)
|
||
|
||
PROD_IOC_vxWorks = example
|
||
example_SRCS += sncExample.stt
|
||
example_LIBS += exampleIoc
|
||
example_LIBS += seq pv
|
||
example_LIBS += $(EPICS_BASE_IOC_LIBS)
|
||
|
||
# example_registerRecordDeviceDriver.cpp will be created from example.dbd
|
||
example_SRCS += example_registerRecordDeviceDriver.cpp
|
||
|
||
#The following adds support from base/src/vxWorks
|
||
example_OBJS_vxWorks += $(EPICS_BASE_BIN)/vxComLibrary
|
||
|
||
</pre>
|
||
</li>
|
||
</ul>
|
||
|
||
<p>After these changes are made the following files are no longer needed:
|
||
baseLIBOBS, Makefile.Host, and Makefile.Vx</p>
|
||
|
||
<h3>File base.dbd no longer needed</h3>
|
||
|
||
<blockquote>
|
||
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.</blockquote>
|
||
|
||
<h3>Record support</h3>
|
||
|
||
<blockquote>
|
||
Add the following line after all existing #includes
|
||
|
||
<blockquote>
|
||
<pre>#include "epicsExport.h"</pre>
|
||
</blockquote>
|
||
The structure rset is now a typedef so change
|
||
|
||
<blockquote>
|
||
<pre>struct rset <recordname>RSET={ ...</pre>
|
||
</blockquote>
|
||
to
|
||
|
||
<blockquote>
|
||
<pre>rset <recordname>RSET={ ...</pre>
|
||
</blockquote>
|
||
and add the following line after the "rset <recordname>RSET="
|
||
definition.
|
||
|
||
<blockquote>
|
||
<pre>epicsExportAddress(rset,xxxRSET);</pre>
|
||
</blockquote>
|
||
</blockquote>
|
||
|
||
<h3>Device support</h3>
|
||
|
||
<blockquote>
|
||
Add the following line after all existing #includes
|
||
|
||
<blockquote>
|
||
<pre>#include "epicsExport.h"</pre>
|
||
</blockquote>
|
||
and add the following line after the dset dev<devname> definition
|
||
|
||
<blockquote>
|
||
<pre>epicsExportAddress(dset,dev<devname>);</pre>
|
||
</blockquote>
|
||
</blockquote>
|
||
|
||
<h3>Driver support</h3>
|
||
|
||
<blockquote>
|
||
Add the following line after all existing #includes
|
||
|
||
<blockquote>
|
||
<pre>#include "epicsExport.h"</pre>
|
||
</blockquote>
|
||
and add the following line after the drvet dev<devname> definition
|
||
|
||
<blockquote>
|
||
<pre>epicsExportAddress(drvet,drv<devname>);</pre>
|
||
</blockquote>
|
||
</blockquote>
|
||
|
||
<h3>Registration code changed</h3>
|
||
|
||
<blockquote>
|
||
Registration code for application specific functions, e.g. subroutine
|
||
record init and process functions, has been changed as follows
|
||
|
||
<p>1) Include the registration support header files:</p>
|
||
|
||
<blockquote>
|
||
<pre>#include "dbDefs.h"
|
||
#include "registryFunction.h"</pre>
|
||
</blockquote>
|
||
2) Include the export definitions header file after including all other
|
||
header files:
|
||
|
||
<blockquote>
|
||
<pre>#include "epicsExport.h"</pre>
|
||
</blockquote>
|
||
3) Make the application specific functions static functions, e.g.
|
||
|
||
<blockquote>
|
||
<pre>static long mySubInit(subRecord *precord,processMethod process)
|
||
static long mySubProcess(subRecord *precord)</pre>
|
||
</blockquote>
|
||
4) Define a registryFunctionRef array of the application specific functions
|
||
to be registered, e.g.
|
||
|
||
<blockquote>
|
||
<pre>static registryFunctionRef mySubRef[] = {
|
||
{"mySubInit",(REGISTRYFUNCTION)mySubInit},
|
||
{"mySubProcess",(REGISTRYFUNCTION)mySubProcess}
|
||
};</pre>
|
||
</blockquote>
|
||
5) Add a new function to do the registration of the registryFunctionRef
|
||
array elements, e.g.
|
||
|
||
<blockquote>
|
||
<pre>void mySub(void)
|
||
{
|
||
registryFunctionRefAdd(mySubRef,NELEMENTS(mySubRef));
|
||
}</pre>
|
||
</blockquote>
|
||
6) Call the epicsExportRegistrar with the new registration function: e.g.
|
||
|
||
<blockquote>
|
||
<pre>epicsExportRegistrar(mySub);</pre>
|
||
</blockquote>
|
||
7) Remove the existing function lines in <appname>Include.dbd: e.g.
|
||
remove
|
||
|
||
<blockquote>
|
||
<pre>function("mySubInit")
|
||
function("mySubProcess")</pre>
|
||
</blockquote>
|
||
8) Add a registrar statement to <name>Include.dbd with the new
|
||
registration function as parameter: e.g. add
|
||
|
||
<blockquote>
|
||
<pre>registrar("mySub")</pre>
|
||
</blockquote>
|
||
</blockquote>
|
||
|
||
<h3>Modify the Makefiles in <top>/iocBoot directory.</h3>
|
||
|
||
<p>Change " i<tt>nclude $(TOP)/config/CONFIG_APP" </tt>to "<tt>include
|
||
$(TOP)/configure/CONFIG"</tt></p>
|
||
|
||
<p>Remove the line "<tt>DIRS += $(wildcard *ioc*"</tt></p>
|
||
|
||
<p>Change <tt>"include $(TOP)/config/RULES.iocBoot" </tt>to "i<tt>nclude
|
||
$(TOP)/configure/RULES.iocBoot"</tt></p>
|
||
|
||
<h3>Modify the Makefiles in <top>/iocBoot/ioc* directories.</h3>
|
||
|
||
<p>Change <tt>"include $(TOP)/config/CONFIG_APP" </tt>to "<tt>include
|
||
$(TOP)/configure/CONFIG"</tt></p>
|
||
|
||
<p>Change</p>
|
||
|
||
<p><tt>include ARCH = <old arch specification e.g. mv167></tt></p>
|
||
|
||
<p>to</p>
|
||
|
||
<p>"<tt>include ARCH = <new arch specification e.g.
|
||
vxWorks-68040>"</tt></p>
|
||
|
||
<p>Change "<tt>include $(TOP)/config/RULES.ioc</tt>" to "<tt>include
|
||
$(TOP)/configure/RULES.ioc"</tt></p>
|
||
|
||
<p>If it exists remove the line</p>
|
||
|
||
<p><tt>buildInstall: cdCommands </tt></p>
|
||
|
||
<p>Add the line</p>
|
||
<p><tt>TARGETS = cdCommands</tt></p>
|
||
<p>befor the include for RULES.ioc line.</p>
|
||
|
||
<h3>Modify st.cmd in <top>/iocBoot/ioc* directories.</h3>
|
||
|
||
<p>Remove the lines</p>
|
||
<pre>ld < seq
|
||
ld < iocCore</pre>
|
||
|
||
<p>Change "<tt>ld < <libname>Lib</tt>" to "<tt>ld <
|
||
<libname>.munch"</tt></p>
|
||
|
||
<p>Change "<tt>cd appbin</tt>" to "<tt>cd topbin</tt>"</p>
|
||
|
||
<p>Change the statement:</p>
|
||
|
||
<p><tt>dbLoadDatabase("../../dbd/exampleApp.dbd")</tt> <br>
|
||
</p>
|
||
to
|
||
<pre>dbLoadDatabase("../../dbd/<name>.dbd")
|
||
<name>_registerRecordDeviceDriver(pdbbase)</pre>
|
||
|
||
<p>where <name> is replaced with the name of your dbd file.</p>
|
||
|
||
<h3>recGbl calls</h3>
|
||
|
||
<p>If any source file makes calls to recGbl routines make sure it has <span
|
||
style="font-family: courier">"#include "recGbl.h"</span>. If it doesn't the
|
||
compiler will issue warning messages and the ioc may issue the message:
|
||
"undefined symbol: _recGblSetSevr".</p>
|
||
|
||
<h3>Record support changes</h3>
|
||
|
||
<p>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 <tt>LIBOBJS</tt> definitions to the src Makefile.</p>
|
||
|
||
<p>For example add</p>
|
||
|
||
<p> <tt>PID=<full path to modules directory>/pid</tt></p>
|
||
|
||
<p>to config/RELEASE and add <br>
|
||
|
||
<p></p>
|
||
|
||
<p><tt>LIBOBJS += $(PID_BIN)/pidRecord.o</tt></p>
|
||
to your application src/Makefile.
|
||
|
||
<p>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.</p>
|
||
|
||
<h3>RecDynLink.o and devPtSoft changes</h3>
|
||
|
||
<p>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
|
||
<tt>LIBOBJS</tt> location definition <tt>$(EPICS_BASE_BIN)</tt> to the module
|
||
definition bin directory in your application src directory files. See
|
||
"Hardware support changes" below for instructions.</p>
|
||
|
||
<h3>Hardware support changes</h3>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>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
|
||
<tt>LIBOBJS</tt> location from <tt>$(EPICS_BASE_BIN) </tt>to the module bin
|
||
directory in your application src directory files.</p>
|
||
|
||
<p>For example, remove</p>
|
||
|
||
<p> <tt>LIBOBJS+=$(EPICS_BASE_BIN)/symb</tt></p>
|
||
|
||
<p>from baseLIBOBJS and add</p>
|
||
|
||
<p> <tt>LIBOBJS+=$(SYMB_BIN)/symb</tt></p>
|
||
|
||
<p>to your application src/Makefile, <br>
|
||
and add the line</p>
|
||
|
||
<p><tt>SYMB=<full path definition for the built module SYMB></tt></p>
|
||
|
||
<p>into your application config/RELEASE file .</p>
|
||
|
||
<h3>dbLoadtemplate tool changes</h3>
|
||
|
||
<p>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</p>
|
||
|
||
<p><tt>MSI=<full path name to msi executable></tt></p>
|
||
|
||
<p>to your application config/RELEASE file.</p>
|
||
<br>
|
||
</body>
|
||
</html>
|