472 lines
14 KiB
HTML
472 lines
14 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</h2>
|
|
</center>
|
|
|
|
<p>This document describes how to convert a R3.13 vxWorks application so that it
|
|
builds with release R3.14. It describes procedures such that:</p>
|
|
<ul>
|
|
<li>The application uses the configure rules which are new to R3.14.</li>
|
|
<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 <tt>gnumake clean uninstall</tt> 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>
|
|
|
|
<blockquote>
|
|
<pre>mkdir <i>top</i>
|
|
cd <i>top</i>
|
|
<i>/path/to/base-3.14</i>/bin/<i>host_arch</i>/makeBaseApp.pl -t example junk</pre>
|
|
</blockquote>
|
|
|
|
<h3>Copy all *App and iocBoot directories and files to the new <i>top</i>
|
|
directory</h3>
|
|
|
|
<blockquote>
|
|
<pre>cd <i>oldtop</i>
|
|
find *App iocBoot -print | cpio -pvmd <i>/path/to/new/top</i></pre>
|
|
</blockquote>
|
|
|
|
<h3>Modify <i>top</i>/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 sncseq external module</p>
|
|
|
|
<blockquote>
|
|
<pre>SNCSEQ = <i>/path/to/sncseq</i></pre>
|
|
</blockquote>
|
|
|
|
<p>The R3.14 sncseq module must exist and be built with the same EPICS base
|
|
R3.14 release.</p>
|
|
|
|
<h3>Modify the Makefiles in <i>top</i>/*App directories.</h3>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
|
|
$(TOP)/configure/CONFIG</tt></q></p>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/RULES_DIRS</tt></q> to <q><tt>include
|
|
$(TOP)/configure/RULES_DIRS</tt></q></p>
|
|
|
|
<h3>Modify the Makefiles in <i>top</i>/*App/*Db directories.</h3>
|
|
|
|
<p>Remove existing <q><tt>Makefile</tt></q>.</p>
|
|
|
|
<p>Rename <q><tt>Makefile.Host</tt></q> to <q><tt>Makefile</tt></q></p>
|
|
|
|
<p>Modify the <tt>Makefile</tt> as follows:</p>
|
|
|
|
<p>Change <q><tt>TOP=../../..</tt></q> to <q><tt>TOP=../..</tt></q></p>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
|
|
$(TOP)/configure/CONFIG</tt></q></p>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/RULES.Db</tt></q>to <q><tt>include
|
|
$(TOP)/configure/RULES</tt></q></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 <i>top</i>/*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>
|
|
|
|
<blockquote>
|
|
<pre>rm Makefile
|
|
cp ../../junkApp/src/Makefile .</pre>
|
|
</blockquote>
|
|
|
|
<p>We can remove the junkApp now (unless you have other App/src directories
|
|
still to convert):</p>
|
|
|
|
<blockquote>
|
|
<pre>rm -rf ../../junkApp</pre>
|
|
</blockquote>
|
|
|
|
<p>This new Makefile 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>
|
|
<blockquote>
|
|
<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>
|
|
</blockquote>
|
|
<p>In Makefile these are:</p>
|
|
<blockquote>
|
|
<pre>PROD_HOST += caExample
|
|
caExample_SRCS += caExample.c
|
|
caExample_LIBS += $(EPICS_BASE_HOST_LIBS)</pre>
|
|
</blockquote>
|
|
</li>
|
|
<li>Record Support - generate xxxRecord.h file
|
|
<p>Makefile.Host (or perhaps Makefile.Vx) contains:</p>
|
|
<blockquote>
|
|
<pre>RECTYPES += xxxRecord.h</pre>
|
|
</blockquote>
|
|
<p>In Makefile this is:</p>
|
|
<blockquote>
|
|
<pre>DBDINC += xxxRecord</pre>
|
|
</blockquote>
|
|
</li>
|
|
<li>Generating the .dbd file for all record/device/driver support
|
|
<p>Makefile.Host (or perhaps Makefile.Vx) contains:</p>
|
|
<blockquote>
|
|
<pre>DBDEXPAND = exampleInclude.dbd
|
|
DBDNAME = exampleApp.dbd</pre>
|
|
</blockquote>
|
|
<p>In Makefile this is:</p>
|
|
<blockquote>
|
|
<pre>DBD += example.dbd</pre>
|
|
</blockquote>
|
|
<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>
|
|
<blockquote>
|
|
<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>
|
|
</blockquote>
|
|
<p>In Makefile these become:</p>
|
|
<blockquote>
|
|
<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>
|
|
</blockquote>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>After these changes are made the following files are no longer needed:
|
|
baseLIBOBJS, Makefile.Host, and Makefile.Vx</p>
|
|
|
|
<h3>File base.dbd no longer needed</h3>
|
|
|
|
<p>You now can add the line</p>
|
|
|
|
<blockquote>
|
|
<pre>include "base.dbd"</pre>
|
|
</blockquote>
|
|
|
|
<p>to your <i>appname</i>Include.dbd file and remove the file
|
|
<i>name</i>App/src/base.dbd from your src directory. The base.dbd from base/dbd
|
|
will be used instead. If you only want to load a subset of the record
|
|
definitions from base you can keep your own copy of base.dbd, but you should
|
|
copy the one from your R3.14 base and edit that rather than trying to re-use the
|
|
R3.13 version from your old application.</p>
|
|
|
|
<h3>Record support</h3>
|
|
|
|
<p>Add the following line after all existing #includes</p>
|
|
|
|
<blockquote>
|
|
<pre>#include "epicsExport.h"</pre>
|
|
</blockquote>
|
|
|
|
<p>The structure rset is now a typedef so change</p>
|
|
|
|
<blockquote>
|
|
<pre>struct rset <i>recordname</i>RSET = { ... };</pre>
|
|
</blockquote>
|
|
|
|
<p>to</p>
|
|
|
|
<blockquote>
|
|
<pre>rset <i>recordname</i>RSET = { ... };</pre>
|
|
</blockquote>
|
|
|
|
<p>and add the following line after the <q>rset <i>recordname</i>RSET = { ...
|
|
};</q> definition.</p>
|
|
|
|
<blockquote>
|
|
<pre>epicsExportAddress(rset,<i>recordname</i>RSET);</pre>
|
|
</blockquote>
|
|
|
|
<h3>Device support</h3>
|
|
|
|
<p>Add the following line after all existing #includes</p>
|
|
|
|
<blockquote>
|
|
<pre>#include "epicsExport.h"</pre>
|
|
</blockquote>
|
|
|
|
<p>and add the following line after the dset definition <q>struct { ... }
|
|
dev<i>name</i> = { ... };</q></p>
|
|
|
|
<blockquote>
|
|
<pre>epicsExportAddress(dset,dev<i>name</i>);</pre>
|
|
</blockquote>
|
|
|
|
<h3>Driver support</h3>
|
|
|
|
<p>Add the following line after all existing #includes</p>
|
|
|
|
<blockquote>
|
|
<pre>#include "epicsExport.h"</pre>
|
|
</blockquote>
|
|
|
|
<p>and add the following line after the drvet drv<i>name</i> definition</p>
|
|
|
|
<blockquote>
|
|
<pre>epicsExportAddress(drvet,drv<i>name</i>);</pre>
|
|
</blockquote>
|
|
|
|
<h3>Registration code changed</h3>
|
|
|
|
<p>Registration code for application specific functions, e.g. subroutine record
|
|
init and process functions, must been changed as follows</p>
|
|
|
|
<ol>
|
|
<li>Include the following header files after all existing #includes:
|
|
<blockquote>
|
|
<pre>#include "registerFunction.h"
|
|
#include "epicsExport.h"</pre>
|
|
</blockquote></li>
|
|
|
|
<li>Make the application specific functions static functions, e.g.
|
|
<blockquote>
|
|
<pre>static long mySubInit(subRecord *precord)
|
|
static long mySubProcess(subRecord *precord)</pre>
|
|
</blockquote></li>
|
|
|
|
<li>Add an epicsExportFunction statement for each of the functions to be
|
|
registered, e.g.
|
|
<blockquote>
|
|
<pre>epicsExportFunction(mySubInit);
|
|
epicsExportFunction(mySubProcess);</pre>
|
|
</blockquote></li>
|
|
|
|
<li>Add a function statement for each of the functions to be registered in a
|
|
.dbd file that is included in the application, e.g.
|
|
<blockquote>
|
|
<pre>function("mySubInit")
|
|
function("mySubProcess")</pre>
|
|
</blockquote></li>
|
|
</ol>
|
|
|
|
<h3>Modify the Makefiles in <i>top</i>/iocBoot directory.</h3>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
|
|
$(TOP)/configure/CONFIG</tt></q></p>
|
|
|
|
<p>If they do not already exist, add the lines</p>
|
|
|
|
<blockquote>
|
|
<pre>DIRS += $(wildcard *ioc*)
|
|
DIRS += $(wildcard as*)</pre>
|
|
</blockquote>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/RULES.iocBoot</tt></q> to <q><tt>include
|
|
$(TOP)/configure/RULES_DIRS</tt></q>.</p>
|
|
|
|
<h3>Modify the Makefiles in <i>top</i>/iocBoot/ioc* directories.</h3>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
|
|
$(TOP)/configure/CONFIG</tt></q></p>
|
|
|
|
<p>Change</p>
|
|
|
|
<blockquote>
|
|
<pre>ARCH = <old arch specification e.g. mv167></pre>
|
|
</blockquote>
|
|
|
|
<p>to</p>
|
|
|
|
<blockquote>
|
|
<pre>ARCH = <new arch specification e.g. vxWorks-68040></pre>
|
|
</blockquote>
|
|
|
|
<p>Change <q><tt>include $(TOP)/config/RULES.ioc</tt></q> to <q><tt>include
|
|
$(TOP)/configure/RULES.ioc</tt></q></p>
|
|
|
|
<p>If it exists remove the line</p>
|
|
|
|
<blockquote>
|
|
<pre>buildInstall: cdCommands</pre>
|
|
</blockquote>
|
|
|
|
<p>Add the line</p>
|
|
|
|
<blockquote>
|
|
<pre>TARGETS = cdCommands</pre>
|
|
</blockquote>
|
|
|
|
<p>before the include for RULES.ioc line.</p>
|
|
|
|
<h3>Modify st.cmd in <i>top</i>/iocBoot/ioc* directories.</h3>
|
|
|
|
<p>Remove the lines</p>
|
|
|
|
<blockquote>
|
|
<pre>ld < seq
|
|
ld < iocCore</pre>
|
|
</blockquote>
|
|
|
|
<p>Change <q><tt>ld < <i>name</i>Lib</tt></q> to
|
|
|
|
<blockquote>
|
|
<pre>ld 0,0, "<i>name</i>.munch"</pre>
|
|
|
|
<p>(The <tt>ld</tt> command in vxWorks 5.5.2 doesn't clean up its standard
|
|
input properly, so we now recommend passing the filename to it directly
|
|
instead.)</p> </blockquote>
|
|
|
|
<p>Change <q><tt>cd appbin</tt></q> to <q><tt>cd topbin</tt></q></p>
|
|
|
|
<p>Change the statement:</p>
|
|
|
|
<blockquote>
|
|
<pre>dbLoadDatabase("../../dbd/<i>name</i>App.dbd")</pre>
|
|
</blockquote>
|
|
|
|
to
|
|
|
|
<blockquote>
|
|
<pre>dbLoadDatabase("../../dbd/<i>name</i>.dbd")
|
|
<i>name</i>_registerRecordDeviceDriver(pdbbase)</pre>
|
|
</blockquote>
|
|
|
|
<p>where <i>name</i> 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 includes
|
|
<tt>recGbl.h</tt>. If it doesn't the compiler will issue warning messages and
|
|
the ioc may issue the message: <q>undefined symbol: _recGblSetSevr</q>.</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>
|
|
|
|
<blockquote>
|
|
<pre>PID = <i>/path/to/modules</i>/pid</pre>
|
|
</blockquote>
|
|
|
|
<p>to config/RELEASE and add</p>
|
|
|
|
<blockquote>
|
|
<pre>LIBOBJS += $(PID_BIN)/pidRecord.o</pre>
|
|
</blockquote>
|
|
|
|
<p>to your application src/Makefile.</p>
|
|
|
|
<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
|
|
<q>Hardware support changes</q> 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>
|
|
|
|
<blockquote>
|
|
<pre>LIBOBJS += $(EPICS_BASE_BIN)/symb</pre>
|
|
</blockquote>
|
|
|
|
<p>from baseLIBOBJS and add</p>
|
|
|
|
<blockquote>
|
|
<pre>LIBOBJS += $(SYMB_BIN)/symb</pre>
|
|
</blockquote>
|
|
|
|
<p>to your application src/Makefile, and add the line</p>
|
|
|
|
<blockquote>
|
|
<pre>SYMB = <full path definition for the built module SYMB></pre>
|
|
</blockquote>
|
|
|
|
<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>
|
|
|
|
<blockquote>
|
|
<pre>MSI = <full path name to msi executable></pre>
|
|
</blockquote>
|
|
|
|
<p>to your application config/RELEASE file.</p>
|
|
</body>
|
|
</html>
|