V4 Link Support Tutorial

EPICS: IOC Link Support Tutorial Oct 26 2005

---

Overview

The V4 link support is a replacement for V3

1. DBF_DEVICE, DBF_INLINK, DBF_OUTLINK, and DBF_FWDLINK
2. device DBD definition and device support
3. driver DBD definition and driver support

The link support model is:

• For each link, record support defines a list of interfaces it can use for communicating with link support
• Link support defines the set of interfaces it implements

Link support has no knowledge of what record types are using it and record support has no knowledge about link support other than the interface it is using.

EPICS base defines a standard set of interfaces for link support. The intention is that the set includes enough functionality such that most link support can be implemented via just these interfaces.

The interfaces support all the functionality needed by Channel/Database access and by the generic EPICS device support supplied by asynDriver. Since asynDriver is intended as a framework for interfacing to most hardware, this means that the interfaces supplied and used by base allows support for most hardware. The support can communicate with the hardware however it wants but must implement some set of the interfaces defined by base.

This document gives a brief overview of the V4 link support model.

---

Database Definitions For Links

This section first reviews the DBD syntax related to link definitions. It then gives a brief description of link related definitions in dbCommon.dbd

Syntax

A record link has the syntax:

    link(linkDirection,interface(interfaceName,...))

A link itself has the syntax:

    link(linkDirection,choiceName,dataStructName,interface(interfaceName,...))

A record instance link definition has the syntax:

    field = { choice(interfaceName) {structAssignmentList}}
     or
    field = { choice(interfaceName) dataStructName {structAssignmentList} }

where

linkDirection

Must be one of none,in,out,process, or inout. Compatible checks are made to match the interface with a field.

interface

This is a list of the interfaces that the record support understands or that link support implements.

choiceName

UTF-8 string that describes the choice

interfaceName

The name of an interface via which record support communicates with link support.

dataStructName

The name of a struct containing configuration information for the link support. Record support normally does not access this structure. Database configuration tools prompt the user to assign values to the structure.

choice

Selects a link with choiceName = choice

A record instance link definition selects a link as follows:

• The linkDirections must be compatible
  • Except for inout the record link and link directions must be the same
  • If record link specifies inout the link can specify either in or out or inout
• The interfaceName specified by the record instance must be in the record link interface list and in the link interface list.
• The dataStructName specified in the record instance must match the dataStructName in the link definition.

Assume the following definitions:

    record(AiRecord) {
        ...
        field(in,link(in,interface(LinkInt64,LinkFloat64)))
        ...
    }
    struct(PvMonitorLink) {
        field(pvname,string)
        field(process,boolean) // process this record when monitor occurs
        field(inheritSeverity,boolean)
    }
    struct(PvInputLink) {
        field(pvname,string)
        field(process,boolean)
        field(wait,boolean)
        field(timeout,float64)
        field(inheritSeverity,boolean)
    }
    ...
    link(in,monitorLink,PvMonitorLink,interface(
        LinkBoolean,
        LinkInt16,LinkInt32,LinkInt64,
        LinkFloat32,LinkFloat64,
        LinkString
    ))
    link(in,inputLink,PvInputLink,interface(
        LinkBoolean,
        LinkInt16,LinkInt32,LinkInt64,
        LinkFloat32,LinkFloat64,
        LinkString
    ))
    ...
    struct VME{
        field(a16,int16) 
        field(a32,int32)
        field(channel,int16)
    }
    ...
    link(in,someVmeADC,VME, interface(LinkInt32))

The first example instance definition selects a monitor link. It selects interface LinkInt32, which means the support will provide a "raw" value that the record support will convert to engineering units.

    AiRecord aiMonitorExample = {
        ...
        in = {monitorLink(LinkInt32) 
                  PvMonitorLink {    
                       pvname = "someRecord";
                        process = true;
                       inheritSeverity = false
                  }
              }

The next example selects a channel access input link. It selects interface LinkFloat64, which means the support will provide a value in engineering units. It asks that the linked record be processed and that the link not complete until the linked record completes processing.

    AiRecord aiInputExample = {
        ...
        in = {inputLink(LinkFloat64) 
                  PvInputLink {    
                       pvname = "someRecord";
                       process = true;
                       wait = true;
                       timeout = 1.0;
                       inheritSeverity = false
                  }
              }

The last example selects support for a VME Analog to Digital device.

    AiRecord aiMonitorExample = {
        ...
        in = {someVmeADC(LinkInt32) VME {a16 = 0xc000; channel = 1} }

Standard Definitions For Channel/Database Access

These are the database definitions defined in dbCommon are used by the base supplied support for Channel/Database access. This support registers each choiceName in the link definitions. The complete set of data structure and link definitions are defined in "V4 DB RecordCommon".

Link support is provided for

• monitor
• input
• output
• process

For monitor, input, and output the following data types are supported:

• primitive types
• string
• arrays of primitive types and strings

asynDriver link support

These are definitions that are used by the standard EPICS device support for asynDriver. Since asynDriver is a generic way of interfacing arbitrary hardware support, this is a generic way of attaching links in records to hardware.

Data Definitions

    struct(AsynLink) {
        field(portName,string)
        field(addr,int32)
        field(timeout,float64)
        field(drvPvt,string)
    }

link definitions

    link(inout,asynInt32,AsynLink,interface(LinkInt32))
    link(in,asynInt32Average,AsynLink,interface(LinkInt32))
    link(in,asynInt32Monitor,AsynLink,interface(LinkInt32))
    link(inout,asynFloat64,AsynLink,interface(LinkFloat64))
    link(in,asynFloat64Average,AsynLink,interface(LinkFloat64))
    link(in,asynFloat64Monitor,AsynLink,interface(LinkFloat64))
    link(in,asynDigitalMonitor,AsynLink,interface(AsynDigital))
    link(inout,asynDigital,AsynLink,interface(AsynDigital)))
    link(inout,asynInt32Array,AsynLink,interface(LinkArrayInt32)))
    link(inout,asynFloat64Array,AsynLink,interface(LinkArrayFloat64)))
    link(inout,asynOctet,AsynLink,interface(AsynOctet)))

This is the set of definitions for the standard EPICS device support implemented by asynDriver. Although, at least for the first few V4 releases, asynDriver will not be part of base, they are shown here because the LinkInt32,... interface definitions are defined as part of base. Again it is expected that almost all hardware support be created by implementing a combination of these link interface definitions or the interfaces implemented by Channel/Database access link support. ---

Link Support

Overview

An arbitrary number of Link Support implementations can exist. An implementation can be either soft support or support that communicates with hardware.

Other link support can also be supplied. Whenever possible support should implement the standard interfaces supplied by EPICS base, since these are the interfaces that the record types supplied with base know how to use.

Soft support should try to implement the same interfaces implemented by the Channel/Database access support supplied with base. The support can, of course, define data structures for it's own use. Implementing these interfaces means that the support will work for the same set of record links as the Channel/Database access support.

Hardware support should, if possible, also implement the same interfaces implemented by the Channel/Database access support. Message based support may also have to implement the AsynOctet interface but this interface is only used by a few record types.

This section describes the interfaces implemented by all link support and then the standard interfaces used by the records supplied with base.

The syntax is similar to Java syntax since it is more concise than C++. It can easily be translated to C++ syntax. For example the definition:

    interface LinkInt16 {
        LinkResult get(Callback callback,Int16 data);
        LinkResult put(Callback callback,Int16 data);
        boolean getBounds(Int16 low, Int16 high);
    }

In C++ would be:

    class LinkInt16 {
    public:
        virtual LinkResult get(Callback &callback, int16_t &data) = 0;
        virtual LinkResult put(Callback &callback, int16_t data) = 0;
        virtual bool getBounds(int16_t &low, int16_t &high) = 0;
    };

Link and MonitorLink

All support must register interface Link and if it supports monitors interface MonitorLink. NOTE: arguments and return types ignored for now

    interface Link {
        void report(int16 level);
        void cancel();
        void destroy();
        void initialize();
        void connect();
        void disconnect();
    }

    interface MonitorLink {
        void addMonitor(Callback callback);
        void removeMonitor();
    }

Link is an interface that must be implemented by every link support. An instance of this is connected to each DbfLink field. The Link methods are:

• report - report
• cancel - Cancel any outstanding I/O
• destroy - This is called if the field is being changed after initialization or if the record is being removed.
• initialize - Called to initialize a link.
• connect - Called to connect. Note that this is different than initilization.
• disconnect - disconnect.

MonitorLink is an interface that is implemented by link support that supports monitors. An example is support for hardware interrupts. The MonitorLink methods are:

• addMonitor - Add a monitor callback
• removeMonitor - Remove monitor

Normally record support does not need to call any of the Link or MonitorLink methods since database access does this automatically. For example if a link field is modified via a channel access put, database access will call destroy before modifying the link and initialize and connect after the link is modified.

Note that neither Link or MonitorLink is listed in the link database definition since they are generic.

Definitions that apply to Process,Monitor,Input,and Output support

These are the definitions used by the Channel/Database access support supplied with base. It is also used by the standard EPICS support from asyn.

    enum LinkResult {
        linkNoop,           // Nothing was done, e.g. link is null link
        linkDone,           // field was modified. No wait is necessary
        linkWait,           // waiting. can do additional procsssing
    }

    interface Callback {
        void done();
        void failure();
    }

Process Link Support

    interface LinkProcess {
        LinkResult process(Callback callback);
    }

Octet Support

    interface LinkOctet {
        LinkResult get(Callback callback, Octet data);
        LinkResult put(Callback callback, octet data);
    }
    interface LinkArrayOctet {
        LinkResult get(Callback callback, octet[] data);
        LinkResult put(Callback callback, octet[] data);
    }

GENERIC QUESTION The data is passed as primitive or arrays of primitive types. Should Dbf interfaces be used? Needs thought.

asynOctet Support

This still needs more work. It attempts to reproduce the functionality of V3 asynDriver.

    interface AsynOctet {
        LinkResult write(Callback callback,
          octet[] data, int32 numchars, Int32 nbytesTransfered);
        LinkResult writeRaw(Callback callback,
          octet[] data, int32 numchars, Int32 nbytesTransfered);
        LinkResult read(Callback callback,
          octet[] data, Int32 nbytesTransfered);
        LinkResult readRaw(Callback callback,
          octet[] data, Int32 nbytesTransfered);
        void flush();
        void setInputEos(octet[] eos);
        void getInputEos(octet[] eos);
        void setOutputEos(octet[] eos);
        void getOutputEos(octet[] eos);
    }

asynDigital Support

    enum interruptReason {
        interruptOnZeroToOne, interruptOnOneToZero, interruptOnBoth
    }
    struct asynDigitalInterrupt {
        octet[] mask;
        int32 addr;
        Callback callback
    }

    interface AsynDigital {
         LinkResult write(Callback callback,octet[] value, octet[] mask);
         LinkResult read(Callback callback,octet[] value, octet[] mask);
         void setInterrupt(octet[] mask, interruptReason reason);
         void clearInterrupt(octet[] mask);
         void getInterrupt(octet[] mask, interruptReason reason);
         void registerInterruptUser(interruptCallbackUInt32Digital callback,
             octet[] mask);
         void cancelInterruptUser();
    }

Boolean Support

    interface LinkBoolean {
        LinkResult get(Callback callback,Boolean data);
        LinkResult put(Callback callback,boolean data);
    }
    interface LinkArrayBoolean {
        LinkResult get(Callback callback,boolean[] data);
        LinkResult put(Callback callback,boolean[] data);
    }

The data source must be a boolean or a string that contains a valid boolean value.

Integer Support

Support is available. for int16, int32, and int64.

    interface LinkInt16 {
        LinkResult get(Callback callback,Int16 data);
        LinkResult put(Callback callback,Int16 data);
        boolean getBounds(Int16 low, Int16 high);
    }
    interface LinkArrayInt16 {
        LinkResult get(Callback callback,int16[] data);
        LinkResult put(Callback callback,int16[] data);
    }
    interface LinkInt32 {
        LinkResult get(Callback callback,Int32 data);
        LinkResult put(Callback callback,Int32 data);
        boolean getBounds(Int32 low, Int32 high);
    }
    interface LinkArrayInt32 {
        LinkResult get(Callback callback,int32[] data);
        LinkResult put(Callback callback,int32[] data);
    }
    interface LinkInt64 {
        LinkResult get(Callback callback,Int64 data);
        LinkResult put(Callback callback,Int64 data);
        boolean getBounds(Int64 low, Int64 high);
    }
    interface LinkArrayInt64 {
        LinkResult get(Callback callback,int64[] data);
        LinkResult put(Callback callback,int64[] data);
    }

Float Support

Support is available. for float32 and float64.

    interface LinkFloat32 {
        LinkResult get(Callback callback,Float32 data);
        LinkResult put(Callback callback,float32 data);
    }
    interface LinkArrayFloat32 {
        LinkResult get(Callback callback,float32[] data);
        LinkResult put(Callback callback,float32[] data);
    }
    interface LinkFloat64 {
        LinkResult get(Callback callback,Float64 data);
        LinkResult put(Callback callback,float64 data);
    }
    interface LinkArrayFloat64 {
        LinkResult get(Callback callback,float64[] data);
        LinkResult put(Callback callback,float64[] data);
    }

String Support

    interface LinkString {
        LinkResult get(Callback callback,string data);
        LinkResult put(Callback callback,string data);
    }
    interface LinkArrayString {
        LinkResult get(Callback callback,string[] data);
        LinkResult put(Callback callback,string[] data);
    }

The data source must be a string.

---

Example - VME ADC support

Assume the VME and link definitions given in the examples at the beginning of this document.

The following is presented with Java syntax. It assumes that there is VME support of the form

    public class vme {
        static public short getShort(long addr);
        ...
    }

The link support would be something like:

    class AdcSupport implements Link LinkInt32 {
    AdcSupport(VME fromFactory)
    {
        addr = fromFactory;
        connected = false;
        //  from the VME initialize vmeaddr and channel
        // details left to your imagination
    }

    // Link methods
    void report(int16_t level)
    {
        printf("AdcSupport a16 %x channel %d\n",a16,channel);
    }
    void cancel() {} // nothing to do
    void destroy() {} //nothing to do
    void initialize()
    {
        // make sure we can access a16
    }
    void connect() {connected = true}
    void disconnect() {connected = false}
    
    // LinkInt32 methods
    LinkResult get(Callback callback, Int data)
    {
        data = (Int)VME.getShort(vmeaddr);
        return linkDone;
    }
    LinkResult put(Callback callback, Int data)
    {
        throw CantWriteAdc;
    }
    void getBounds(Int low, Int high) 
    {
        // assume 16 bit unipolor adc
        low = 0; high = 0xffff;
    }
    private:
        VME addr;
        int vmeaddr;
        int channel;
        boolean connected;
    }

---

Discussion of link support interfaces

Overview

The link definitions: record link, link, record instance links, and the link interfaces are designed to support channel/database links, links to hardware support, and links to other types of support.

The following are two important requirements:

• analog I/O
  • link support can return raw value. Support must convert to engineering units.
  • link support can return engineering units
• output records
  • Can link support provide initial value?
  • What if multiple sources can change linked output?

Lets consider each of these separately.

Analog I/O

In V3 the aiRecord and aoRecords are responsible for conversion between raw values and engineering units. Raw values are 32 bit integers. Device support is responsible for setting the slope and intercept fields of the record. Record support takes care of the actual conversions. Device support can tell record support that it set the engineering units rather than a raw value by a different return value.

NOTE:Perhaps in V4 aiRecord should be separated into two records, e.g. a record that always uses float values and an ADC record which handles raw values. Another possibility is special link support that provides floating values to the record support and links to the actual hardware support. For this discussion it is assummed that aiRecord and aoRecord are still responsible for conversions since most of the discussion is independent of how the record support is structured.

For V4 the following is done:

aiRecord and aoRecord both have the following fields:

    menu(menuConvert) {
        choice(menuConvertRaw, "Raw")
        choice(menuConvertLinear, "Linear")
        choice(menuConvertTable, "Table")
    }

    struct(LinearConvert) {
        field(eguf,float64)
        field(egul,float64)
        field(slope,float64)
        field(intercept,float64)
    }

    ...
    field(convert, menu(menuConvert))
    field(linearConvert, struct(LinearConvert))
    field(convertTable,string);
    field(units, string)

The link field for aiRecord is

    field(in,link(in,interface( LinkInt32, LinkFloat64)))

The link field for aoRecord is

    field(out,link(out,interface( LinkInt32, LinkFloat64)))

When a record instance is defined the link specifies the interface to use. If the interface is:

• LinkInt32 - Then the link support supplies raw values
• LinkFloat64 - Then the link support supplies engineering units

LinkInt32 is defined as:

    interface LinkInt32 {
        LinkResult get(Callback callback,Int32 data);
        LinkResult put(Callback callback,Int32 data);
        void getBounds(Int32 low, Int32 high);
    }

Thus link support is responsible for returning the ADC bounds. For example support for a 16 bit unipolar ADC would set low=0, high=65535, and return true. If link support can not determine the bounds then getBounds returns false.

If the link interface is LinkFloat64 then record support does no conversion. Thus the following only applys if the interface is LinkInt32.

Record support handles conversions as follows:

• Raw - The value obtained from the link support is converted to a double.
• Linear
  • If link support returned the bounds record support computes slope and intercept
  • otherwise it uses the slope and intercept from instance definition
• Table - The interface implementation for convertTable is located and used.

NOTE:The interface implemented by breakpoint tables must be defined. It will support the same semantics as the V3 breakpoint tables.

Output Records

The following are two features that link support should implement whenever possible:

1. When a record is initalized provide the current value of the output
2. If something else modifies the actual output value in the record

The first feature is especially desirable when an IOC is rebooted. If a hardware output can survive a reboot this is a very desirable feature. If the output is to a field bus, a PLC, or to a record in another IOC it is often possible for the link support to determine the current value.

The second feature is something that was often asked for in V3 but only implemented for some special cases. This is especially desirable when the output is connected to a system that can have multiple sources of control. Examples are GPIB devices with front pannel controls, PLC systems that have manual controls or non-epics network access.

For V3 some of the hardware , but none of the soft, support implemented the first feature but by modifying actual fields in the record. V3 did not implement the second feature. Some special device support, not part of base, was implemented to support this feature.

For V4 these features are supported as follows:

record initialization

The link support implements an interface that has a put and a get method. For example:

    interface LinkInt32 {
        LinkResult get(Callback callback,Int32 data);
        LinkResult put(Callback callback,Int32 data);
        boolean getBounds(Int32 low, Int32 high);
    }

If the link support can support readbacks then it implements get and returns linkDone. If it does not support readbacks then it implements get by just returning linkNoop.

monitors for outputs

If output link support can detect when something besides the link support itself modifies the output then it implements interface MonitorLink

    interface MonitorLink {
        void addMonitor(Callback callback);
        void removeMonitor();
    }

At initialization record support looks for this interface and if found it calls addMonitor. The link support calls the callback whenever it detects a change in the output that it did not cause. Record support causes itself to be processed without making a new call to the link support.