EPICS Release baseR3.13.0.beta4

Nov 8, 1996

All major functionality that will be in R3.13 is now in place and at least partially tested. If you dont give feedback soon it will be too late for 3.13. It has not been tested on all architectures. The only ones I am sure have been tested are solaris, sunos, and HPUX.

The Application Developer's Guide is a major revision of the 3.12 edition. All Application Developer's should get a hard copy (from the postscript version) and read it. It describes the features in the latest release. The latest version is for beta4 base release.

Major Tasks Remaining

The only tasks remaining before an official release are:

Changes between beta2 and beta4

Notes for Release 3.13 of EPICS Base

For Release 3.13 major changes have been made to EPICS base. The IOC Application Developer's Guide has been extensively modified and now describes release 3.13. If you are upgrading for a 3.12.xxx or earlier release you must obtain and read the new App dev Guide.

In porting EPICS to multiple architectures, the previous method of using utilities to convert the database definition files to a binary file (default.dctsdr) caused problems. The problem is that the binary file is created on one architecture and used on another. This has worked so far for sun4 and hp hosts combined with motorola 68xxx processors. As support for more host and more ioc architectures is developed problems are appearing. This paper describes changes that solve the problems.

Because the changes result in extensive changes to database access, other changes are also made. The file syntax is changed. The internal database structures are simplified and also changed to make it easier to support runtime add/delete of record types and record instances.

Goals

Backward Compatibility

Incompatibilities

Overview of new database support

EPICS defines a set of database file formats. In addition any of these files can contain include statements. For each ioc, the application developer will create a set of files specifying the record types, devices, and drivers needed for that ioc. Normally a master file will be created which consists of include statements that bring in record, device, and driver definitions. Default configurations can be provided for new users or for particular applications.

Database configuration and utility tools access the database via the static database access library. This library reads the files. It provides routines for reading the information in the database and for creating and modifying record instances. Database definition files can be read incrementally.

Other database configuration tools (capfast, relational database systems, object oriented databases, etc.) can also be used as long as they generate record instances in the format described below. In this case, however, it is still necessary to generate the other files because they are needed by database access and for record and device support modules.

Tools are provided that generate C code from the database files. Header files are generated for menu and record type definitions. These header files are used by record and device support. In addition the record type definitions contain code which computes field offsets and sizes and record sizes. This code is compiled by the same cross compiler that is used to compile other ioc code. Thus cross platform compatibility is achieved.

In order to initialize an ioc, all files needed by that ioc have to be loaded. It is also necessary to load the record/device/driver support modules.

Everything is designed so that the following are possible:

An additional feature is that, for database configuration tools, record instance numeric fields and menu fields are stored as character strings. This solves the following problems.

Another feature is is that it is now possible to distinguish link constants with a value of 0 from links that have never been given a value.

Other changes have been made while the opportunity was available.

Database Definition File format

Formats are defined for the following: See the Application Developer's Guide for details.

The menu choices replace the existing global, record, and conversion choices. The global and record choices are very similar and thus are easy to combine. The method of handling the old conversion choices is described below. That section also describes the breakpoint tables.

The record type description format has been completely changed. It now has a "real" syntax. It should be MUCH easier to generate new definitions.

The device choice and driver support definitions are defined so that it is easy to provide incremental definitions.

The record instance format is an extension of the 3.12.beta13 and later GDCT .db format.

Path and include statements are supported. This provides a powerful tool for combining definitions from many sources. The path is a unix style path, i.e. a colon separated list of directory names.

default.dctsdr conversion tools

NOTES

The following tools are provided:

For all utilities the required database definition files are generated from a dctsdr file from a previous epics release. A dctsdr file can be specified or else the utilities can be run in a directory which contains default.dctsdr (or a soft link with that name). sdr2recordtype also requires the header file generated by a previous epics release.

Conversions - replacement for DBF_CVTCHOICE

Let's briefly review database conversion, i.e. the LINR field for ai and ao records.

The allowed conversions are:

  1. None
  2. Linear
  3. Breakpoint Tables
The main complication results from the breakpoint tables. Previously EPICS handled breakpoint tables as follows:

The user prepares files in one of two formats: The first is just a list of "raw value, eng units value". The second format is a file with a header line followed by a table of raw data values that represent data at equally spaced engineering unit values. In either case the ascii data is converted to an internal binary format containing breakpoint tables. This data is part of default.dctsdr.

Here is how breakpoint table are now handled.

One other comment needs to be made about conversions. The Allen Bradley device support for the IXE module uses the LINR field in a non standard way. This was a mistake but compatibility must be maintained. Thus menuConvert contains a lot of choices used only by the IXE device support.

Converting existing applications

Database Configuration Tools

  • DCT - Rather than making major changes to DCT, a TCL/TK replacement has been written. The executable is named DCT313.
  • GDCT - A new version is provided that supports 3.13. The executable is named GDCT313.
  • CAPFAST

    Application Source/Release Control

    At the present time There are at least three Application Source/Release Control Systems in active use. The old technique of having cat_ascii and replace_ascii directories no longer work. In addition makesdr no longer exists. The new system offers developers far more flexibility but it also means that each Application Source/Release Control system has to be modified to take advantage of the new capabilities. Again the changes in RULES and makeBaseApp should make this task easier.

    The Application Developer's Guide describes a utility makeBaseApp, which is sufficient for small applications and test environments.

    Locally developed Record/Device support

    Record Instance Definitions

    Convert to proper format

    All record instances must be capable of being loaded into an ioc via dbLoadDatabase, dbLoadRecords, or dbLoadTemplate. This is the same format that dbLoadRecords and dbLoadTemplate used in 3.12 releases. Note that if any files contain the statements: 
    	database(x) { nowhere() {
	}
	}

or

	database(x) {
	}
    These statements must be removed. They were in pre 3.12 releases.

    CONSTANT Links with value "0"

    Release 3.13 is now capably of distingushing between a null link (a link that is not given any value at all) and a constant link with the value 0. This cause problems for some old record instance files. For example if a record instance is defined as: 
    	record(fanout,name) {
		field(SELN,"1")
		field(SELL,"0")
	}
    Such definitions can be fixed by either completly removing the link definition or changing the value from "0" to "".

    here is a complete list of record types and fields that may have this problem:

    A good way to find these problems is to use grep. For example: 
    	grep SELL */*.db
    This assumes that you are in directory that contains subdirectorys containing .db files.

    IOC Startup files

    The command dbLoad is no longer supported. The new method is to issue one or more dbLoadDatabase commands and any combination of dbLoadRecords and dbLoadTemplate commands.

    Other Release Notes

    Make rules and config files

    The config environment has been extensively changed. BASE now has its own set of config files. Extensions will be able to use the base config files (for the version of base it is built against) and add it's own definitions. Changes to extensions will come at a future time.

    GNU C++ for base

    It is now possible to compile 3.13 EPICS base with the gnu C and C++ compilers. A C++ compiler that properly supports templates is required to build the new ca server and the gdd library.

    log server

    Thanks to William Lupton at KECK the log server will now (under the latest EPICS 3.13) obtain a new directory for the log file in response to SIGHUP.

    CA repeater fix

    Thanks to Kim Gillies, Bret Goodrich, and others at NOAO a problem has been discovered and fixed in the 3.12 CA repeater under solaris.

    Portable CA server

    A new CA server C++ class library is available. The server library is in libcas.a. The API is described in casdef.h. Doc is in progress. An example server tool can be found at base/src/cas/example. The server has been tested under sunos4 and solaris. A multi-threaded version of the new server for vxWorks is in progress.

    Macro Substitution Library

    The macro substitution library discussed in tech-talk is now part of epics base. Thus was contributed by Bill Lupton. The static database library uses this library.

    VXI Resource Manager fix

    Thanks to Ric Claus of SLAC a bug has been isolated in the VXI resource manager.
    Symptom: correct slot isnt located when EPICS_VXI_LA_BASE is set to something other than zero.

    Access Security

    If asSetFile has been set in a startup file and access security initialization fails, then iocInit returns -1 so that startup file does not finish.

    errPrintf

    On Unix this now calls fprintf(stderr instead of printf

    iocLogClient.c

    This now calls printf instead of epicsPrintf to prevent deadlocks.

    Native type for DBF_USHORT

    Formerlly old database access, which does not have unsigned short called the native type DBR_FLOAT. It now calls it DBF_LONG

    Allen Bradley Driver

    Analog Output Block Transfers were being requested too frequently

    If link_status command fails (3 times in succession) adapters are now immediatly declared down.

    For btRead and btWrite, The driver now enforces a timeout of 5 seconds which is 1 second more than scanner itself enforces. This is so that if scanner throws away a BT request it will still timeout.

    For btRead and btWrite is is no longer permissible to issue a new btRead or btWrite from tha callback routine.

    The on line doc has the following two changes:

    vmic2534

    Support has been added by LBL. It still needs to be ansified.

    New options for links

  • FWDLINK
    A forward link now works between IOCs but only if the field is PROC. When recGblFwdLink is executed, a 1 is written.
  • OUTLINK new option CA (In addition to PP and NPP)
    CA means always make it channel access link
  • INLINK new options CA CP CPP (In addition to PP and NPP) dbAccess (dbGetField dbPutField) make sure that link field strings are not longer than 39 characters. They allow M for MS and N for NMS

    callback and scan task names

    The task names have been changed to make them unique

    dbPutString

    If the strlen of the new field is >= field_size an error is returned.

    event scanned records

    Multiple priorities are now supported.
    WARNING: Default PRIO is low thus old event scanned records may be executed at a lower priority then previous release.

    Stepper Motor Support (Ric Claus SLAC)

    These release notes describe changes made to stepper motor related code that was supplied with EPICS Version R3.12.2 SLAC $Date: 1996/01/28 01:38:17 $. Additionally, support is described for the Allen Bradley 1746-HSTP1 stepper motor controller module.

    The basic modification was to move the implementation of the initialization algorithm (supplied through the IALG field in a stepper motor record) from the record support code (recSteppermotor.c) to the device or driver support code. This allows the specific device to determine how to move the stepper motor to the positive or negative limit. Both of the stepper motor drivers standardly supplied with EPICS (drvCompuSm.c and drvOms.c) were modified to accommodate this change. Other nonstandard stepper motor support codes will need modification to handle the new SM_FIND_LIMIT (defined in steppermotor.h) command (see the CompuMotor or OMS codes for examples).

    In addition, two new algorithms have been added to the list of initialization algorithm choices. These are "Move to Positive Home" and "Move to Negative Home", which are implemented through the new SM_FIND_HOME command. These were added in accommodation of the new device support for the Allen Bradley 1746-HSTP1 stepper motor controller (devSmAB1746HSTP1.c), which allows the use of a home limit switch in addition to the standard end point limit switches. Nonstandard device and driver support for stepper motor controllers which do not have this capability should be modified to ignore or complain when they receive the SM_FIND_HOME command (cf, drvCompuSm.c or drvOms.c).

    The new device support code for the Allen Bradley 1746-HSTP1 stepper motor controller requires the EPICS standard issue Allen Bradley driver (drvAb.c).

    From the comments at the top of devSmAB1746HSTP1.c [perhaps good for inclusion into the "EPICS: AllenBradley Driver and Device Support" manual?]:

    Device support for the 1746-HSTP1 module was written assuming that there are no wiring errors. Consequently, if your apparatus does not agree throughout itself which direction is clockwise (+) and which direction is counterclockwise (-), unexpected things may happen.

    The 1746-HSTP1 device support code was written from the perspective of the Allen Bradley 1746-HSTP1 module. Clockwise (+) is therefore defined to be the direction in which the stepper motor axis turns when it is viewed from the shaft end of the motor, as per page 4-18 of the 1746-HSTP1 User's Manual (AB Pub No. 1746-999-121, March 1995).

    The 1746-HSTP1 devices have no hardware configuration switches or jumpers to be concerned with. However, "HSTP1 CONFIG OUTPUT WORDs" (Pages 4-4 and A-1 of the User's Manual) must be passed to the device support layer in the parm section of the stepper motor record .OUT field. The string is parsed with the format string "%hi%hi%i" and is allowed to be a maximum of AB_PARAM_SZ (currently #defined to be 26 in include/link.h) characters long. Use only whitespace to separate the values. The three values that must be supplied are: 

         Hstp1CfgCsr[0] - Configuration word
     Hstp1CfgCsr[1] - Active level word
     Hstp1StartSpd  - Starting speed word (1 - 250000 pulses/sec)

  An example param string is:    0x8413 0x0010 500
    Page 4-4 of the User's Manual states that valid configurations require the home limit switch input and one or both of the end (CW or CCW) limit switch inputs to be enabled, even if the associated switch is not present.

    Due to the way in which the HSTP1 handles limit switch conditions, it is best to avoid them. If a limit switch has been activated, one can either issue a Find Home command to the HSTP1 to make it hunt for the home switch, or issue single step (Jog) commands to bump the jig off the switch. The jogging procedure is very slow since it requires a reading the HSTP1 registers to get the current state of the limit switches, a clearing of the HSTP1 command register to make the appropriate jog bit sensitive to transition and a setting of the appropriate jog bit in the command register. A 25 MHz NI VXIcpu-030 operating with an AB 6008-SV1R scanning module can thus achieve a jog rate of about 3 Hz. If a position request causes the jig to run into one of the switches, the only motion requests that are accepted by this code are those that move the jig in the direction of getting off of the switch, again, presuming no wiring errors.

    One of the rules of writing EPICS device support code is that the process routine must complete as fast as possible since any delays in it cause other records to be held up. For this reason all commands to this device support layer issued by the record support process routine are queued onto a message queue. The reason it is done this way rather than processing the commands directly is that there are sometimes delays in getting access to the hard- ware, either the VME scanner, or the controller itself. Because it is easy to set up a situation in which EPICS sends commands to this code faster than they can be processed, one must handle the case where the queue fills up. When the queue is full, we break the rules and wait for up to HSTP1_K_EPICSQDLY seconds for previously entered commands to be taken off the queue in an attempt to throttle EPICS. If the timeout expires, bad status is returned to indicate that the command could not be handled at the time. Typically, the queue is configured to be deep enough that this situation never arises.

    In order to reduce the chance of a knobbed .VAL field from overflowing the command queue, the motor is declared to be moving as soon as a motion request is recognized, even though it is not necessarily moving yet. This prevents the record support layer from sending out corrections until the motor arrives at the requested spot. However, there is a problem because if the position request is changed while the motor is still moving, it will be ignored by the record support. To prevent this, supply a non-zero retry count and an appropriate deadband when setting up your database. Additionally, always put knobs and sliders in "release" mode rather than in "motion" mode.

    The basic scan rate when there are active stepper motors is 1/3 second. When there are no active stepper motors, this code sleeps. Consequently, any manual motion of the stepper motor axes is not accounted for.

    This code can, in principle, handle an arbitrary number of 1746-HSTP1 stepper motor controller modules. However, limitations are provided by memory, semaphore, and message queue resources, and bus and "blue hose" bandwidths. Note that this code spawns only two tasks, both of which are terminated with corresponding resources freed if no stepper motor records are found in the system.

    initHooks

    INITHOOKafterCaLinkInit1 is replaced by INITHOOKafterCaLinkInit
    INITHOOKafterCaLinkInit2 no longer exists