Contents:
Introduction
User's Guide
Software
Installation
System
Configuration
Running
the Nameserver
Command
Line Options
Programmer's Guide
Software
Description
Introduction
The nameserver is used at Jefferson Lab to provide IP
addresses of EPICS process variables (PVs) to client programs. Without
a nameserver, client broadcast searches for PVs add to the load of
every IOC in the system. With the nameserver in use, broadcasts
are directed only to the nameserver, decreasing the load on the IOCs.
Performance tests have shown that PV connection time is twice as
fast when using the nameserver.
Two modes of operation are available. In normal mode, information about the location of control system process variables (PVs) is loaded into internal hashtables at startup. In learn mode, a client request for information about an unknown PV triggers a broadcast by the nameserver.If the PV is found, location information is added to the hashtable. At Jefferson Lab, we use a combination of both modes, preloading data for for 96 IOCs and ~280k PVs and learning on demand about other less frequently requested PVs. Preloading results in more deterministic operation and a startup time of less than 5 seconds. If the nameserver is running as a daemon process and a crash or restart is done, clients attempting to connect will see a 5 second delay but there will be no effect on clients which have already connected.
The nameserver runs on a Unix workstation and is based on EPICS Portable Channel Access Server(PCAS) and the PCAS example program "directoryServer".
User's Guide
Software Installation
The distributed gzipped tar file contains source code,
makefiles, and sample configuration files. We use the EPICS utility "makeBaseApp"
to provide an environment for compiling the source code using Makefile.Host.
Scripts and documentation for "makeBaseApp" are available as part
of the EPICS distribution with documentation in the file "$EPICS/base/src/makeBaseApp/iocAppBuildSRcontrol.html".
At Jefferson Lab, EPICS configuration files are set up to use HP-UX 10.20
and the HP aCC compiler but the code has compiled on Linux or Solaris
without difficulty. Before compiling, edit the file "directoryServer.h"
and modify the section labelled "SITE SPECIFIC MODIFICATIONS", following
the instructions in that file. The executable, "caDirServ", should
be copied to the directory from which it will run. Note that only one PCAS
application may be run from any host.
System Configuration
At least two files must be created before the nameserver
can be run. The first file, with the defaultname "pvDirectory.txt", must
contain a list of full pathnames to one or more secondary files each
called "signal.list". The name, "signal.list",
may be changed before the code is compiled. At Jefferson Lab, our "pvDirectory.txt"
file contains 96 lines of text:
/cs/op/iocs/iocmc1/signal.list
/cs/op/iocs/iocmc2/signal.list
etc.
The next to last component of each pathname must be the
name of the IOC. The "pvDirectory.txt" file is best located in the
same directory as the executable code.
Our "signal.list" files are automatically created by
each IOCs on bootup by using the command "dbpr >> signal.list". These files
may be created by any convenient method but must contain one PV name per
line.
Currently, there is one more requirement that must be met. Each "signal.list" file must contain one PV named "iocname:heartbeat" and this PV must exist on the actual IOC. The suffix, ":heartbeat", may be changed before the code is compiled. At Jefferson Lab, these PVs update a counter every second and are used on medm screens to indicate that the IOC is running. They may, in fact, be associated with any type of record.
There is one exception to the set of requirements above. If the file "pvDirectory" is empty, the nameserver will run in total learn mode. This is not recommended for most efficient operation but may be useful for testing.
Running the Nameserver
Set the environmental variables "EPICS_CA_ADDR_LIST"
and "EPICS_CA_AUTO_ADDR_LIST" so that IOC's can be "seen" by the
nameserver. This can be done in the "start_nameserver" script.
cd to the directory containing the nameserver executable
and start "caDirServ".
Verify that the nameserver has created two new files
in this home directory: "nameserver.killer" and "nameserver.restart".
To test the code, from another xterm, set "EPICS_CA_ADDR_LIST'
to the IP address of the machine which is running the nameserver. Set "EPICS_CA_AUTO_ADDR_LIST"
to "NO" to avoid problems with the client seeing the PVs twice, once
directly and again via the nameserver.
Verify that the nameserver is running by using "caget"
to read the value of "iocname:heartbeat". If the "caget"is successful,
attempt to get the values of other PVs on the same IOC and then on other
IOCs.
From the original xterm, kill the nameserver by executing
the nameserver.killer script.
Start the nameserver again using the -s argument to run
as a daemon process. Note that a log file is created.
Verify operation as above.
Execute the nameserver.restart script and confirm that
the original log file has been moved to a backup file and a new one has
been created, and that new killer and restart files have been
created.
To exercise the reporting option, look at the contents of the nameserver.killer file and find the line after the comment "use the following to get a PV summary report in log:". This will be a "kill -USR1 PID" command. View the log file before and after executing the command. Similarly, the USR2 signal will start a new log file.
Command Line Options
The nameserver front end is modelled after the EPICS
PCAS gateway code, and like the gateway, it may be run manually or as a
daemon process. As a daemon process, the executable can be signaled
to quit, to restart or to display run-time statistics. A log file may be
created in manual mode and will be created if the server is run as a daemon.
Command line arguments include:
-f filename ......modify the
name of the default input file "pvDirectory.txt"
-d nnn.............turn on and set
the level of PCAS debugging
-l logfilename ..requests that
logging be done and allows specification of logfile name
-c directory .......change
operational directory
-s ....................use server
mode
-h nnn ..............set hashtable
size (default = 300,000)
-v ....................verbose mode
Included with the distributed code is the file "start_nameserver". This script sets environmental variables and executes the nameserver process with standard arguments.
Programmer's Guide
Software Description
caDirServ is based on the Portable Channel Access Server library and the example code "directoryServer", both of which are part of the EPICS base distribution files. For information about PCAS, please see the EPICS web site at Los Alamos, "http://mesa53.lanl.gov/lansce8/Epics/ca/ca.htm".
The EPICS PCAS library provides many virtual functions which are normally replaced by the application developer, This application uses only the "pvExistTest" function. The usual "read" and "write" functions are not used and are effectively noops. The library provides all low level code for channel access. On receipt of a client broadcast, the library code calls the application "pvExistTest" function with the PV name as an argument. In the nameserver code, the PV hashtable is checked. If the PV is found, the IOC hashtable is checked to verify that the IOC is up. If true, the function returns "pvExistReturn" along with socket address information for the appropriate IOC. If the PV is not found in the PV hashtable, the nameserver will attempt to learn by broadcasting to find the PV and will return "pverDoesNotExistHere" for each request for this PV until the information is known. If the PV is known but the IOC is down, "pverDoesNotExistHere" will be returned. The rest of the code is bookkeeping.
The nameserver maintains information on the status of each IOC by setting up a channel access monitor for each "heartbeat" PV and receiving channel access connection events. In this way, a PV can be added, deleted or moved from one IOC to another and the disconnection/connection sequence from the IOC will trigger updates to both the status of the IOCs and the contents of the PV hashtable. When a PV is moved from one IOC to another, it is important to reboot the IOC which loses the PV before rebooting the IOC which gains the PV.
The C++ code is quite simple with just over 1800 lines of source code. In addition to the PCAS library, the nameserver uses two EPICS hashtables to store information about PVs and IOCs and an EPICS singly linked list to keep track of PVs for which broadcasts have been done but haven't yet been found or timed out. A third hash table stores the names of PVs which never connect.
Unlike earlier versions of nameservers, no modifications are necessary to either EPICS/base or to client code. Clients simply modify EPICS_CA_ADDR_LIST to direct broadcasts to the nameserver. The program has been most effective when serving medm or burt, both of which do extensive broadcasting.
The only problems seen so far are with client code which has been compiled with very old versions of EPICS which use channel access protocol version 4.4. This code has had to be recompiled to work with the nameserver.
This release of the code includes minor modifications
to logging. It also includes two #ifdef'd sections. The first, "JS_FILEWAIT",
is no longer used at JLab. At one time, the nameserver
would attempt to read incomplete signal.list files. Now our iocs write
their files before ioc initialization and this delaying code is no longer
needed here. The second #ifdef'd section, "PIOC", provides for serving
PIOC variables which may be deleted without a loss of a heartbeat. The
signal USR2 has been recoded as one way of handling these deletions.
Please send bug reports, fixes or comments to:
Joan Sage
[email protected]