This chapter provides a brief introduction to creating EPICS IOC applications. It contains:
This chapter will be hard to understand unless you have some familarity with IOC concepts such as record types, device and driver support and have had some experience with creating ioc databases. Once you have this experience, this chapter provides most of the information needed to build applications. The example that follows assumes that EPICS base has already been built.
This section explains how to create an example IOC application in a directory <top>, naming the application myexampleApp and the ioc directory iocmyexample.
Execute the command:
This should display your workstation architecture, for example linux-x86 or win32-x86. If you get an “Undeﬁned variable” error, you should set EPICS_HOST_ARCH to your host operating system followed by a dash and then your host architecture, e.g. solaris-sparc. The perl script EpicsHostArch.pl in the base/startup directory has been provided to help set EPICS_HOST_ARCH.
The following commands create an example application.
Here, <arch> indicates the operating system architecture of your computer. For example, solaris-sparc. The last command will ask you to enter an architecture for the IOC. It provides a list of architectures for which base has been built.
The full path name to <base> (an already built copy of EPICS base) must be given. Check with your EPICS system administrator to see what the path to your <base> is. For example:
Windows Users Note: Perl scripts must be invoked with the command perl <scriptname> on Windows. Perl script names are case sensitive. For example to create an application on Windows:
Spend some time looking at the ﬁles that appear under <top>. Do this before building. This allows you to see typical ﬁles which are needed to build an application without seeing the ﬁles generated by make.
The sequencer is now supported as an unbundled product. The example includes an example state notation program, sncExample.stt. As created by makeBaseApp the example is not built or executed.
Before sncExample.stt can be compiled, the sequencer module must have been built using the same version of base that the example uses.
To build sncExample edit the following ﬁles:
#seq sncExample, "user=<user>"
The Makeﬁle contains commands for building the sncExample code both as a component of the example IOC application and as a standalone program called sncProgram, an executable that connects through Channel Access to a separate IOC database.
In directory <top> execute the command
NOTE: On systems where GNU make is not the default another command is required, e.g. gnumake, gmake, etc. See you EPICS system administrator.
This time you will see the ﬁles generated by make as well as the original ﬁles.
The example can be run on vxWorks, RTEMS, or on a supported host.
After the ioc is started try some of the shell commands (e.g. dbl or dbpr <recordname>) described in the chapter “IOC Test Facilities”. In particular run dbl to get a list of the records.
The iocsh command interpreter used on non-vxWorks IOCs provides a help facility. Just type:
where <cmd> is one of the commands displayed by help. The help command accepts wildcards, so
will provide information on all commands beginning with the characters db. On vxWorks the help facility is available by ﬁrst typing:
An example host example can be generated by:
(or gnumake, as required by your operating system)
Two channel access examples are provided:
<mytop>/bin/<hostarch>/caExample <pvname> where
Because the vxWorks shell is only available on vxWorks, EPICS base provides iocsh. In the main program it can be invoked as follows:
If the argument is a ﬁlename, the commands in the ﬁle are executed and iocsh returns. If the argument is 0 then iocsh goes into interactive mode, i.e. it prompts for and executes commands until an exit command is issued.
This shell is described in more detail in Chapter 18, “IOC Shell”.
On vxWorks iocsh is not automatically started. It can be started by just giving the following command to the vxWorks shell.
To get back to the vxWorks shell just say
Detailed build rules are given in chapter 4 “Build Facility”. This section describes methods for building most components needed for IOC applications. It uses excerpts from the myexampleApp/src/Makefile that is generated by makeBaseApp.
The following two types of applications can be built:
These are applications meant for use by ioc applications. The rules described here install things into one of the following directories that are created just below <top>:
These are applications loaded into actual IOCs.
Because many IOC components are bound only during ioc initialization, some method of linking to the appropriate shared and/or static libraries must be provided. The method used for IOCs is to generate, from an xxxInclude.dbd ﬁle, a C++ program that contains references to the appropriate library modules. The following database deﬁnitions keywords are used for this purpose:
The method also requires that IOC components contain an appropriate epicsExport statement. All components must contain the statement:
Any component that deﬁnes any exported functions must also contain:
Each record support module must contain a statement like:
Each device support module must contain a statement like:
Each driver support module must contain a statement like:
Functions are registered using an epicsRegisterFunction macro in the C source ﬁle containing the function, along with a function statement in the application database description ﬁle. The makeBaseApp example thus contains the following statements to register a pair of functions for use with a subroutine record:
The database deﬁnition keyword variable forces a reference to an integer or double variable, e.g. debugging variables. The xxxInclude.dbd ﬁle can contain deﬁnitions like:
The code that deﬁnes the variables must include code like:
The keyword registrar signiﬁes that the epics component supplies a named registrar function that has the prototype:
This function normally registers things, as described in Chapter 21, “Registry” on page 697. The makeBaseApp example provides a sample iocsh command which is registered with the following registrar function:
The DBDINC rule looks for a ﬁle xxxRecord.dbd. From this ﬁle a ﬁle xxxRecord.h is created and installed into <top>/include
The DBD rule ﬁnds myexampleSupport.dbd in the source directory and installs it into <top>/dbd
The LIBRARY_IOC variable requests that a library be created and installed into <top>/lib/<arch>
The myexampleSupport_SRCS statements name all the source ﬁles that are compiled and put into the library.
The above statements are all that is needed for building many support applications.
The following statements build the IOC application:
PROD_IOC sets the name of the ioc application, here called myexample.
The DBD deﬁnition myexample.dbd will cause build rules to create the database deﬁnition include ﬁle
myexampleInclude.dbd from ﬁles in the myexample_DBD deﬁnition. For each ﬁlename in that deﬁnition, the created myexampleInclude.dbd will contain an include statement for that ﬁlename. In this case the created myexampleInclude.dbd ﬁle will contain the following lines.
When the DBD build rules ﬁnd the created ﬁle myexampleInclude.dbd, the rules then call dbExpand which reads myexampleInclude.dbd to generate ﬁle myexample.dbd, and install it into <top>/dbd.
An arbitrary number of myexample_SRCS statements can be given. Names of the form
<name>_registerRecordDeviceDriver.cpp, are special; when they are seen the perl script
registerRecordDeviceDriver.pl is executed and given <name>.dbd as input. This script generates the <name>_registerRecordDeviceDriver.cpp ﬁle automatically.
makeBaseApp.pl is a perl script that creates application areas. It can create the following:
makeBaseApp.pl creates directories and then copies template ﬁles into the newly created directories while expanding macros in the template ﬁles. EPICS base provides two sets of template ﬁles: simple and example. These are meant for simple applications. Each site, however, can create its own set of template ﬁles which may provide additional functionality. This section describes the functionality of makeBaseApp itself, the next section provides details about the simple and example templates.
makeBaseApp has four possible forms of command line:
List the application templates available. This invocation does not alter the current directory.
Create application directories.
Create ioc boot directories.
Options for all command forms:
Arguments unique to makeBaseApp.pl [-t type] [options] app ...:
Arguments unique to makeBaseApp.pl -i [options] ioc ...:
To create a new <top> issue the commands:
makeBaseApp does the following:
When copying certain ﬁles from the template to the new application structure, makeBaseApp replaces some predeﬁned tags in the name or text of the ﬁles concerned with values that are known at the time. An application template can extend this functionality as follows:
This creates ﬁles appropriate for building a support application.
Without the -i option, this creates ﬁles appropriate for building an ioc application. With the -i option it creates an ioc boot directory.
Without the -i option it creates ﬁles for running an example. Both a support and an ioc application are built. With the -i option it creates an ioc boot directory that can be used to run the example.
This builds two Channel Access clients.
This builds an example Portable Access Server.
The vxWorks boot parameters are set via the console serial port on your IOC. Life is much easier if you can connect the console to a terminal window on your workstation. On Linux the ‘screen’ program lets you communicate through a local serial port; run screen /dev/ttyS0 if the IOC is connected to ttyS0.
The vxWorks boot parameters look something like the following:
The actual values for each ﬁeld are site and IOC dependent. Two ﬁelds that you can change at will are the vxWorks boot image and the location of the startup script.
Note that the full path name for the correct board support boot image must be speciﬁed. If bootp is used the same information will need to be placed in the bootp host’s conﬁguration database instead.
When your boot parameters are set properly, just press the reset button on your IOC, or use the @ command to commence booting. You will ﬁnd it VERY convenient to have the console port of the IOC attached to a scrolling window on your workstation.
RTEMS uses the vendor-supplied bootstrap mechanism so the method for booting an IOC depends upon the hardware in use.
Many boards can use BOOTP/DHCP to read their network conﬁguration and then use TFTP to read the applicaion program. RTEMS can then use TFTP or NFS to read startup scripts and conﬁguration ﬁles. If you are using TFTP to read the startup scripts and conﬁguration ﬁles you must install the EPICS application ﬁles on your TFTP server as follows:
Use DHCP site-speciﬁc option 129 to specify the path to the IOC startup script.
Motorola single-board computers which employ PPCBUG should have their ‘NIOT’ parameters set up like:
Controller LUN =00
Device LUN =00
Node Control Memory Address =FFE10000
Client IP Address =‘Dotted-decimal’ IP address of IOC
Server IP Address =‘Dotted-decimal’ IP address of TFTP/NFS server
Subnet IP Address Mask =‘Dotted-decimal’ IP address of subnet mask (255.255.255.0 for class C subnet)
Broadcast IP Address =‘Dotted-decimal’ IP address of subnet broadcast address
Gateway IP Address =‘Dotted-decimal’ IP address of network gateway (0.0.0.0 if none)
Boot File Name =Path to application bootable image (..../bin/RTEMS-mvme2100/test.boot)
Argument File Name =Path to application startup script (..../iocBoot/ioctest/st.cmd)
Boot File Load Address =001F0000 (actual value depends on BSP)
Boot File Execution Address =001F0000 (actual value depends on BSP)
Boot File Execution Delay =00000000
Boot File Length =00000000
Boot File Byte Offset =00000000
BOOTP/RARP Request Retry =00
TFTP/ARP Request Retry =00
Trace Character Buffer Address =00000000
Motrola single-board computers which employ MOTLOAD should have their network ‘Global Environment Variable’ parameters set up like:
mot-/dev/enet0-cipa=‘Dotted-decimal’ IP address of IOC
mot-/dev/enet0-sipa=‘Dotted-decimal’ IP address of TFTP/NFS server
mot-/dev/enet0-snma=‘Dotted-decimal’ IP address of subnet mask (255.255.255.0 for class C subnet)
mot-/dev/enet0-gipa=‘Dotted-decimal’ IP address of network gateway (omit if none)
mot-/dev/enet0-file=Path to application bootable image (..../bin/RTEMS-mvme5500/test.boot)
rtems-client-name=IOC name (mot-/dev/enet0-cipa will be used if this parameter is missing)
rtems-dns-server=’Dotted-decimal’ IP address of domain name server (omit if none)
rtems-dns-domainname=Domain name (if this parameter is omitted the compiled-in value will be used)
epics-script=Path to application startup script (..../iocBoot/ioctest/st.cmd)
The mot-script-boot parameter should be set up like:
where the -c, -s, -m and -g values should match the cipa, sipa, snma and gipa values, respectively and the -f value should match the ﬁle value.
For IOCs which use NFS for remote ﬁle access the EPICS initialization code uses the startup script pathname to determine the parameters for the initial NFS mount. If the startup script pathname begins with a ‘/’ the ﬁrst component of the pathname is used as both the server path and the local mount point. If the startup script pathname does not begin with a ‘/’ the ﬁrst component of the pathname is used as the local mount point and the server path is “/tftpboot/” followed by the ﬁrst component of the pathname. This allows the NFS client used for EPICS ﬁle access and the TFTP client used for bootstrapping the application to have a similar view of the remote ﬁlesystem.
The RTEMS ‘Cexp’ add-on package provides the ability to load object modules at application run-time. If your RTEMS build includes this package you can load RTEMS IOC applications in the same fashion as vxWorks IOC applications.