epics/pcas
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

HTML refactoring.

Browse Source
This commit is contained in:
Andrew Johnson
2009-01-07 20:44:51 +00:00
parent 579c7bad06
commit a294e3dcb8
1 changed files with 222 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

392
documentation/ConvertingR3.13AppsToR3.14.html
View File

@@ -13,13 +13,10 @@
<h2>Converting an EPICS R3.13 application to R3.14</h2>
</center>
<p><br>
This document describes how to convert a R3.13 vxWorks application so that it
<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>
</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>
@@ -27,110 +24,135 @@ builds with release R3.14. It describes procedures such that:</p>
<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>
<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>
<pre>mkdir &lt;top&gt;
cd &lt;top&gt;
&lt;full path to 3.14 base&gt;/bin/&lt;host_arch&gt;/makeBaseApp.pl -t example junk</pre>
<h3>Copy all *App and iocBoot directories and files to the new &lt;top&gt;
<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>
<pre>cd &lt;oldtop&gt;
find *App iocBoot -print | cpio -pvmd &lt;fullpath name to new top&gt;</pre>
<h3>Modify &lt;top&gt;/configure/RELEASE</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 seq external module</p>
SNCSEQ location definition for the R3.14 sncseq external module</p>
<p><tt>SNCSEQ =&lt;full path to seq module top&gt;</tt></p>
The R3.14 seq module must exist and be built with the same EPICS base R3.14
release.
<blockquote>
<pre>SNCSEQ = <i>/path/to/sncseq</i></pre>
</blockquote>
<h3>Modify the Makefiles in &lt;top&gt;/*App directories.</h3>
<p>The R3.14 sncseq module must exist and be built with the same EPICS base
R3.14 release.</p>
<p>Change "<tt>include $(TOP)/config/CONFIG_APP</tt>" to "<tt>include
$(TOP)/configure/CONFIG</tt>"</p>
<h3>Modify the Makefiles in <i>top</i>/*App directories.</h3>
<p>Change " i<tt>nclude $(TOP)/config/RULES_DIRS</tt>" to "<tt>include
$(TOP)/configure/RULES_DIRS</tt>"</p>
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
$(TOP)/configure/CONFIG</tt></q></p>
<h3>Modify the Makefiles in &lt;top&gt;/*App/*Db directories.</h3>
<p>Change <q><tt>include $(TOP)/config/RULES_DIRS</tt></q> to <q><tt>include
$(TOP)/configure/RULES_DIRS</tt></q></p>
<p>Remove existing Makefile <br>
Rename Makefile.Host to Makefile <br>
Modify Makefile as follows:</p>
<h3>Modify the Makefiles in <i>top</i>/*App/*Db directories.</h3>
<p>Change "<tt>TOP=../../..</tt>" to "<tt>TOP=../..</tt>"</p>
<p>Remove existing <q><tt>Makefile</tt></q>.</p>
<p>Change "<tt>include $(TOP)/config/CONFIG_APP</tt>" to "<tt>include
$(TOP)/configure/CONFIG</tt>"</p>
<p>Rename <q><tt>Makefile.Host</tt></q> to <q><tt>Makefile</tt></q></p>
<p>Change "<tt>include $(TOP)/config/RULES.Db" </tt>to "<tt>include
$(TOP)/configure/RULES</tt>"</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 &lt;top&gt;/*App/src directories.</h3>
<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>
<pre>rm Makefile
<blockquote>
<pre>rm Makefile
cp ../../junkApp/src/Makefile .</pre>
</blockquote>
<p>We can remove the junkApp now.</p>
<pre>/bin/rm -fr ../../junkApp</pre>
<p>We can remove the junkApp now (unless you have other App/src directories
still to convert):</p>
<p>This new Make file has comments explaining how to build the various host
<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>
<pre>PROD += caExample
<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>
Com_DIR = $(EPICS_BASE_LIB)</pre>
</blockquote>
<p>In Makefile these are:</p>
<pre>PROD_HOST += caExample
<blockquote>
<pre>PROD_HOST += caExample
caExample_SRCS += caExample.c
caExample_LIBS += $(EPICS_BASE_HOST_LIBS)
</pre>
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>
<pre>RECTYPES += xxxRecord.h
</pre>
<blockquote>
<pre>RECTYPES += xxxRecord.h</pre>
</blockquote>
<p>In Makefile this is:</p>
<pre>DBDINC += xxxRecord
</pre>
<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>
<pre>DBDEXPAND = exampleInclude.dbd
DBDNAME = exampleApp.dbd
</pre>
<blockquote>
<pre>DBDEXPAND = exampleInclude.dbd
DBDNAME = exampleApp.dbd</pre>
</blockquote>
<p>In Makefile this is:</p>
<pre>DBD += example.dbd
</pre>
<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>
<pre>SRCS.c += ../xxxRecord.c
<blockquote>
<pre>SRCS.c += ../xxxRecord.c
SRCS.c += ../devXxxSoft.c
LIBOBJS += xxxRecord.o
@@ -140,10 +162,11 @@ LIBOBJS += sncExample.o
include ../baseLIBOBJS
LIBNAME = exampleLib
INSTALLS += iocCore seq
</pre>
INSTALLS += iocCore seq</pre>
</blockquote>
<p>In Makefile these become:</p>
<pre>LIBRARY_vxWorks += exampleIoc
<blockquote>
<pre>LIBRARY_vxWorks += exampleIoc
exampleIoc_SRCS += xxxRecord.c
exampleIoc_SRCS += devXxxSoft.c
exampleIoc_LIBS += $(EPICS_BASE_IOC_LIBS)
@@ -158,9 +181,8 @@ example_LIBS += $(EPICS_BASE_IOC_LIBS)
example_SRCS += example_registerRecordDeviceDriver.cpp
#The following adds support from base/src/vxWorks
example_OBJS_vxWorks += $(EPICS_BASE_BIN)/vxComLibrary
</pre>
example_OBJS_vxWorks += $(EPICS_BASE_BIN)/vxComLibrary</pre>
</blockquote>
</li>
</ul>
@@ -169,111 +191,112 @@ baseLIBOBJS, Makefile.Host, and Makefile.Vx</p>
<h3>File base.dbd no longer needed</h3>
<p>You now can add the line</p>
<blockquote>
You now can add the line include "base.dbd" to your
&lt;appname&gt;Include.dbd file and remove the file
&lt;name&gt;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>
<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>
Add the following line after all existing #includes
<blockquote>
<pre>#include "epicsExport.h"</pre>
<pre>#include "epicsExport.h"</pre>
</blockquote>
The structure rset is now a typedef so change
<blockquote>
<pre>struct rset &lt;recordname&gt;RSET={ ...</pre>
</blockquote>
to
<p>The structure rset is now a typedef so change</p>
<blockquote>
<pre>rset &lt;recordname&gt;RSET={ ...</pre>
<blockquote>
<pre>struct rset <i>recordname</i>RSET = { ... };</pre>
</blockquote>
and add the following line after the "rset &lt;recordname&gt;RSET="
definition.
<blockquote>
<pre>epicsExportAddress(rset,&lt;recordname&gt;RSET);</pre>
<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>
</blockquote>
<h3>Device support</h3>
<p>Add the following line after all existing #includes</p>
<blockquote>
Add the following line after all existing #includes
<blockquote>
<pre>#include "epicsExport.h"</pre>
<pre>#include "epicsExport.h"</pre>
</blockquote>
and add the following line after the dset definition: struct { ...}
dev&lt;devname&gt;= { ...};
<blockquote>
<pre>epicsExportAddress(dset,dev&lt;devname&gt;);</pre>
<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>
</blockquote>
<h3>Driver support</h3>
<p>Add the following line after all existing #includes</p>
<blockquote>
Add the following line after all existing #includes
<blockquote>
<pre>#include "epicsExport.h"</pre>
<pre>#include "epicsExport.h"</pre>
</blockquote>
and add the following line after the drvet dev&lt;devname&gt; definition
<blockquote>
<pre>epicsExportAddress(drvet,drv&lt;devname&gt;);</pre>
<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>
</blockquote>
<h3>Registration code changed</h3>
<blockquote>
Registration code for application specific functions, e.g. subroutine
record init and process functions, must been changed as follows
<p>Registration code for application specific functions, e.g. subroutine record
init and process functions, must been changed as follows</p>
<p>1) Include the following header files:</p>
<ol>
<li>Include the following header files after all existing #includes:
<blockquote>
<pre>#include "registerFunction.h"
#include "epicsExport.h"</pre>
</blockquote></li>
<blockquote>
<pre>#include "epicsExport.h"
#include "registerFunction.h"</pre>
</blockquote>
2) Make the application specific functions static functions, e.g.
<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>
<blockquote>
<pre>static long mySubInit(subRecord *precord)
static long mySubProcess(subRecord *precord)
</pre>
</blockquote>
3) Add an epicsExportFunction statement for each of the functions to be
registered, e.g.
<li>Add an epicsExportFunction statement for each of the functions to be
registered, e.g.
<blockquote>
<pre>epicsExportFunction(mySubInit);
epicsExportFunction(mySubProcess);</pre>
</blockquote></li>
<blockquote>
<pre>epicsExportFunction(mySubInit);
epicsExportFunction(mySubProcess);
</pre>
</blockquote>
4) Add a function statement for each of the functions to be registered in a
.dbd file that is included in the application, e.g.
<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>
<blockquote>
<pre>function("mySubInit")
function("mySubProcess")
</pre>
</blockquote>
</blockquote>
<h3>Modify the Makefiles in <i>top</i>/iocBoot directory.</h3>
<h3>Modify the Makefiles in &lt;top&gt;/iocBoot directory.</h3>
<p>Change " i<tt>nclude $(TOP)/config/CONFIG_APP" </tt>to "<tt>include
$(TOP)/configure/CONFIG</tt>"</p>
<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>
@@ -282,62 +305,83 @@ $(TOP)/configure/CONFIG</tt>"</p>
DIRS += $(wildcard as*)</pre>
</blockquote>
<p>Change "<tt>include $(TOP)/config/RULES.iocBoot</tt>" to "<tt>include
$(TOP)/configure/RULES_DIRS</tt>".</p>
<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 &lt;top&gt;/iocBoot/ioc* directories.</h3>
<h3>Modify the Makefiles in <i>top</i>/iocBoot/ioc* directories.</h3>
<p>Change "<tt>include $(TOP)/config/CONFIG_APP</tt>" to "<tt>include
$(TOP)/configure/CONFIG</tt>"</p>
<p>Change <q><tt>include $(TOP)/config/CONFIG_APP</tt></q> to <q><tt>include
$(TOP)/configure/CONFIG</tt></q></p>
<p>Change</p>
<p><tt>ARCH = &lt;old arch specification e.g. mv167&gt;</tt></p>
<blockquote>
<pre>ARCH = &lt;old arch specification e.g. mv167&gt;</pre>
</blockquote>
<p>to</p>
<p><tt>ARCH = &lt;new arch specification e.g. vxWorks-68040&gt;</tt></p>
<blockquote>
<pre>ARCH = &lt;new arch specification e.g. vxWorks-68040&gt;</pre>
</blockquote>
<p>Change "<tt>include $(TOP)/config/RULES.ioc</tt>" to "<tt>include
$(TOP)/configure/RULES.ioc</tt>"</p>
<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>
<p><tt>buildInstall: cdCommands</tt></p>
<blockquote>
<pre>buildInstall: cdCommands</pre>
</blockquote>
<p>Add the line</p>
<p><tt>TARGETS = cdCommands</tt></p>
<blockquote>
<pre>TARGETS = cdCommands</pre>
</blockquote>
<p>before the include for RULES.ioc line.</p>
<h3>Modify st.cmd in &lt;top&gt;/iocBoot/ioc* directories.</h3>
<h3>Modify st.cmd in <i>top</i>/iocBoot/ioc* directories.</h3>
<p>Remove the lines</p>
<pre>ld &lt; seq
<blockquote>
<pre>ld &lt; seq
ld &lt; iocCore</pre>
</blockquote>
<p>Change "<tt>ld &lt; &lt;libname&gt;Lib</tt>" to "<tt>ld &lt;
&lt;libname&gt;.munch</tt>"</p>
<p>Change <q><tt>ld &lt; <i>name</i>Lib</tt></q> to
<p>Change "<tt>cd appbin</tt>" to "<tt>cd topbin</tt>"</p>
<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>
<p><tt>dbLoadDatabase("../../dbd/&lt;name&gt;App.dbd")</tt> <br>
</p>
to
<pre>dbLoadDatabase("../../dbd/&lt;name&gt;.dbd")
&lt;name&gt;_registerRecordDeviceDriver(pdbbase)</pre>
<blockquote>
<pre>dbLoadDatabase("../../dbd/<i>name</i>App.dbd")</pre>
</blockquote>
<p>where &lt;name&gt; is replaced with the name of your dbd file.</p>
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 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>
<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>
@@ -351,15 +395,17 @@ add <tt>LIBOBJS</tt> definitions to the src Makefile.</p>
<p>For example add</p>
<p><tt>PID=&lt;full path to modules directory&gt;/pid</tt></p>
<blockquote>
<pre>PID = <i>/path/to/modules</i>/pid</pre>
</blockquote>
<p>to config/RELEASE and add <br>
</p>
<p>to config/RELEASE and add</p>
<p></p>
<blockquote>
<pre>LIBOBJS += $(PID_BIN)/pidRecord.o</pre>
</blockquote>
<p><tt>LIBOBJS += $(PID_BIN)/pidRecord.o</tt></p>
to your application src/Makefile.
<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
@@ -372,7 +418,7 @@ 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>
<q>Hardware support changes</q> below for instructions.</p>
<h3>Hardware support changes</h3>
@@ -390,18 +436,23 @@ directory in your application src directory files.</p>
<p>For example, remove</p>
<p><tt>LIBOBJS+=$(EPICS_BASE_BIN)/symb</tt></p>
<blockquote>
<pre>LIBOBJS += $(EPICS_BASE_BIN)/symb</pre>
</blockquote>
<p>from baseLIBOBJS and add</p>
<p><tt>LIBOBJS+=$(SYMB_BIN)/symb</tt></p>
<blockquote>
<pre>LIBOBJS += $(SYMB_BIN)/symb</pre>
</blockquote>
<p>to your application src/Makefile, <br>
and add the line</p>
<p>to your application src/Makefile, and add the line</p>
<p><tt>SYMB=&lt;full path definition for the built module SYMB&gt;</tt></p>
<blockquote>
<pre>SYMB = &lt;full path definition for the built module SYMB&gt;</pre>
</blockquote>
<p>into your application config/RELEASE file .</p>
<p>into your application config/RELEASE file.</p>
<h3>dbLoadtemplate tool changes</h3>
@@ -411,9 +462,10 @@ 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=&lt;full path name to msi executable&gt;</tt></p>
<blockquote>
<pre>MSI = &lt;full path name to msi executable&gt;</pre>
</blockquote>
<p>to your application config/RELEASE file.</p>
<br>
</body>
</html>