V4 Design: Runtime Interfaces

EPICS: IOC Runtime Interfaces November 03 2005

---

Overview

This document describes definitions for IOC runtime, i.e. interfaces implemented or used by database access, record support, link support, and device support.

It assumes knowledge of the interfaces described in dbdInterfaces.

NOTES

• IOC runtime needs lots more work
• methods, arguments, and return values are likely to undergo many changes

The example code presented in this document assume the following database definitions:

    struct(DisplayLimit) {
        field(low,double)
        field(high,double)
    }

    record(Example) extends RecordCommon {
        field(common,struct(RecordCommon))
        field(fboolean,boolean)
        field(octet,octet)
        field(fint,int16)
        ...
        field(ffloat,float64)
        field(string,string)
        field(array,array(double[])
        field(mdarray,array(double[,])
        field(menu,menu(name))
        field(fenum,enum)
        field(link,link(in))
        field(device,link(in,analogIO))
        field(displayLimit,struct(DisplayLimit))
    }

---

Record Support

    enum ProcessState {
        processCancel,
        processStart,
        processContinue,
        processFinish,
    }

    enum ProcessReturn {
        processDone,
        processAbort,
        processActive
    }

    interface RecordSupport {
        void destroy();
        void initialize(int16 pass);
        ProcessReturn process(ProcessState state,Callback done);
        // if special returns false when after is false put fails
        boolean special(boolean after,Dbf[] field);
    }

ProcessState supports the following semantics:

• cancel - If the record is active terminate
• For all other states see the companion document "V4 Design: Record Processing"

The methods of RecordSupport are:

• destroy - Called when a record instance is deleted.
• initialize - Called twice (pass = 0,1) when a record is initialized.
  • pass 0 - Can do all local initialization but can not attach to anything external
  • pass 1 - Can attach to external things
• process - Called to process a record. See "V4 Design: Record Processing" for semantics.
• special - Called when a field declared special in a DBD file is modified. field is an array of Dbfs showing which field is being modified.

Discussion of special

Special is passed a Dbf array that identifies the field being modified. For example ExampleRecord.dbd has a field:

    field(displayLimit,struct(displayLimit))

ExampleRecordSupport.java might implement special as follows:

    boolean special(boolean after, Dbf[] field)
    {
        switch(field[0].getIndex()) {
        ...
        case ExampleRecord.displayLimitIndex:
            if(field.length==1) {
                // displayLimits itself is being modified. Do something
            } else {
               // a field of displayLimits is being modified
                switch(field[1].getIndex) {
                    case DisplayLimit.lowIndex:
                         // low being modified. do something
                    case DisplayLimit.highIndex:
                         // high being modified. do something
                }
            }
        ...
        }
    }

---

Support for link and struct fields

Support can be provided for link and struct fields. An arbitrary number of Support implementations can exist. An implementation can be either soft support or support that communicates with hardware.

Recall that the support DBD definition is:

   support(choiceName, supportStructName)

choiceName is the name that identifies the implementation. supportStructName is the name of a structure used by support for configuration.

The syntax for interface definitions 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;
    };

NOTE: Int16 becomes int16_t &data and int16 data becomes int16_t data.

Support and SupportMonitor are interfaces that are common to the support for both link and struct fields. All support must register interface Support and if it supports monitors interface SupportMonitor.

NOTE: arguments and return types ignored for now

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

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

Support is an interface that must be implemented by every support module. An instance of this is connected to each DbfLink or DbfStruct field that is configured to use support. The Support 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.

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

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

Normally recordSupport does not need to call any of the Support or SupportMonitor 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. ---

Link Support

Overview

This section describes the standard interfaces used by the record types supplied with epics base. These interfaces are appropriate for the soft support supplied with EPICS base and should also be sufficient for a wide variety of hardware support. In particular they sufficient for communication with asynDriver.

Soft support should try to implement the same interfaces implemented by the Channel/Database access support supplied with base. The support can define support 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.

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

These are the definitions used by the Channel/Database access support supplied with base.

    enum LinkResult {
        linkNoop,           // Nothing was done, e.g. link is null link
        linkNoop,           // field was modified. No wait is necessary
        linkWait,           // waiting for completion 
    }

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

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);
    }

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. ---

Struct Support

support for RecordCommon

This implements an interface, not yet defined, that is similar to the interface record support implements.

support for LinearConvert

This implements the interface

    interface SupportLinearConvert{
         void convert(int32 raw,Float64 value) // from raw to eng
         void convert(float64 value,Int32 raw) // from eng to raw
    }

In addition it provides a factory

    interface FactoryLinearConvert{
        SupportLinearConvert create(string choiceName,
            DbfStruct linearConvert,DbfLink inlink)
    }

support for simulation

This needs to be defined.

support for breakpoint tables

This needs to be defined.

---

Runtime Database Access

Overview

Database Access, with help from record, link, and device support implements the dbdInterfaces. Other than Database Access, fields of a record can only be accessed via the interfaces described in dbdInterfaces. This allows the database to handle actions like posting database monitors without any help from record, link, or device support.

Database access by default allocates the actual storage for each field but allows support code to register itself to manage storage for field instances. Two examples, both involving arrays, are:

• The compress record registers to provide storage for the value.
  • This allows it to implement a circular buffer.
  • Code that accesses the value field may have to issue two get requests.
• Device support for a transient recorder registers to provide storage for the array
  • This allows device support to read data from hardware in segments
  • Code that accesses the array may have to issue many get requests.

The fact that each field of a record instance is an object means that additional storage is required. Database Access will probably have something like the following:

   class Field {
       DbRecord instance;
       short          index;
   };
   ...
   class IntField extends Field {
       int data;
   }
   ...

This each field has the overhead of

• instance - a reference to DbRecord, i.e. record instance
• index - a 16 bit integer
• vtbl - a reference to the object implementation

Additional fields will be needed for things like monitors. These fields can start out null and only allocate storage as needed.

Database Access

    interface DbAccess {
        void lock(RecordInstance instance);
        void unlock(RecordInstance instance);
        void process(RecordInstance instance, Callback callback);
        void processCancel(RecordInstance instance, Callback callback);
        void processContinue(RecordInstance instance, Callback callback);
        void processRequestAccept(Dbf field, boolean yesNo);
        void registerDbfSource(Dbf field, Dbf source);
        LinkSupport getLinkSupport(Dbf field);
        Support getSupport(Dbf field);
        RecordSupport getRecordSupport(RecordInstance instance);
        RecordSupport getRecordCommonSupport(RecordInstance instance);
    }

The methods are:

• lock - lock the record.
• unlock - unlock the record.
• process - Request processing. Record must be idle or active or request fails.
  • instance - The record to process
  • callback - A callback to call when processing completes or for failure.
• processRequestAccept - Should a process request from channel access be accepted,
• registerDbfSource - Register code that will implement storage for the field.
• getLinkSupport - Find the link support for a link field
• getSupport - Get the device support for a device field
• getRecordSupport - Get the record support for the record
• getRecordCommonSupport - Get the RecordCommon support for the record.

NOTES This is just the beginning of defining the methods in DbAccess

---

Code generated from Database Definition Files

The following shows the Java code generated from DBD files:

structure definitions

Two files are generated from struct(name) definitions.

1. name.java
2. nameSupport.java

name.java implements:

    interface Struct {
        Dbf getField(int16 index);
    }

If a structure is defined as:

    struct(DisplayLimit) {
        field(low,double)
        field(high,double)
    }

A generated file DisplayLimit.java contains:

    public class DisplayLimit implements Struct{
        public DbfFloat64 low;
        public DbfFloat64 high;
        public static final short lowIndex = 1;
        public static final short highIndex = 2;
        public static final short lastIndex = indexHigh;
        Dbf getField(short index) {
            switch(index) {
                case lowIndex: return(low);
                case highIndex: return(high);
                default: throw java.lang.IllegalStateException;
            }
            return null;
        }
    }

A generated file DisplayLimitAccess.java contains:

    public class DisplayLimitData {
        public double low;
        public double high;
    }
    public final class DisplayLimitAccess implements StructFactory{
        public Struct create() { return new DisplayLimit; }
        public static final void get(DbfStruct from,DisplayLimitData data) {
            DbfFloat64 dbf = from.getInterface(1);
            data.low = dbf.get();
            DbfFloat64 dbf = from.getInterface(2);
            data.high = dbf.get();
        }
        public static final void put(DbfStruct to, DisplayLimitData data) {
            DbfFloat64 dbf = to.getInterface(1);
            dbf.put(data.low);
            DbfFloat64 dbf = to.getInterface(2);
            dbf.put(data.high);
        }
    }

    public final class DisplayLimitAccessRegister {
        static public createAndRegister() {
            DisplayLimitAccess access = new DisplayLimitAccess;
            RegisterSupport.structure(access,"DisplayLimit");
        }
    }

NOTES

• The V4 replacement for registerRecordDeviceDriver must call DisplayLimitAccessRegister.createAndRegister.
• For non primitive fields the generated field is the Dbf type for the field.

Similar files are generated for C++.

record definitions

If a record is defined as:

    record(Example) {
        field(common,struct(RecordCommon))
        ...
        field(fboolean,boolean)
        field(octet,octet)
        field(fint,int16)
        ...
        field(ffloat,float64)
        field(string,string)
        field(array,array(double[])
        field(mdarray,array(double[,])
        field(menu,menu(name))
        field(fenum,enum)
        field(link,link(in))
        field(device,link(in,analogIO))
        field(displayLimit,struct(DisplayLimit))
    }

The generated Java file is

    public class ExampleRecord implements Struct {
        ... // all the fields from menuStructBase
        public DbfBoolean   fboolean;
        public DbfOctet     ctet;
        public DbfInt16     fint;
        ...
        public DbfFloat64   ffloat;
        public DbfString    string;
        public DbfArray     array;
        public DbfMDArray   mdarray;
        public DbfMenu      menu;
        public DbfEnum      fenum;
        public DbfLink      link;
        public DbfDevice    device;
        public DbfStruct    displayLimit;
        public static final int16 fbooleanIndex = 1;
        ...
        public static final int16 lastIndex = displayLimitIndex;
        Dbf getField(short index) {
            switch(index) {
                case fbooleanIndex : return(fboolean);
                ...
                case displayLimitIndex: return(displayLimit);
                default: throw java.lang.IllegalStateException;
            }
        }
    }

    public final class ExampleRecordFactory implements StructFactory{
        public static final Struct create() { return new ExampleRecord; }
    }

    public final class ExampleRecordFactoryRegister {
        static public createAndRegister() {
            ExampleRecordFactory  factory = new ExampleRecordFactory;
            RegisterSupport.record(factory,"ExampleRecord");
        }
    }

NOTE The V4 replacement for registerRecordDeviceDriver must call ExampleRecordFactoryRegister.createAndRegister

Similar code is generated for C++.

---

Support Code

This section described interfaces for strings, arrays, and conversions. They are intended for use by Database Access, Record Support, etc.

C++ support for strings

For most strings all the database needs is a nonmutable string.

Perhaps the only type of string connected with an IOC record that changes frequently is a field in a record type like stringin and stringout.

This what to do for strings?

array copy

ArrayCopy copies arrays an array performing conversions if necessary.

    interface ArrayCopy {
        void copy(DbfArray from,DbfArray to);
    }

This only supports primitive types, i.e. DbfBoolean,...,DbfFloat64. It does NOT convert between

• DbfBoolean and another type.
• DbfOctet and another type.

Thus for DbfBoolean and DbfOctet it is willing to copy but not convert to/from other types.

Arithmetic Conversions

This is a static class that converts between primitie types and arrays of primitive types.

    static class DbfConvertPrimitive {
    public:
         int16 get(Dbf from);
         int32 get(Dbf from);
         int64 get(Dbf from);
         float32 get(Dbf from);
         float64 get(Dbf from);
         get(Dbf from, String value);
         get(DbfOctet from, String value);
         get(DbfBoolean from, String value);
         put(Dbf to, int16 value);
         put(Dbf to, int32 value);
         put(Dbf to, int64 value);
         put(Dbf to, float32 value);
         put(Dbf to, float64 value);
         put(Dbf to,int32 String value);
         put(DbfOctet to, String value);
         put(DbfBoolean to, String value);

         get(DbfArray from, int16[] value);
         get(DbfArray from, int32[] value);
         get(DbfArray from, int64[] value);
         get(DbfArray from, float32[] value);
         get(DbfArray from, float64[] value);
         put(DbfArray to, int16[] value);
         put(DbfArray to, int32[] value);
         put(DbfArray to, int64[] value);
         put(DbfArray to, float32[] value);
         put(DbfArray to, float64[] value);
    }

NOTES:

• For Dbf to and from must be one of DbfInt16, ..., DbfFloat64
• The get to a string implements printf semantics
• The put from a string value just scanf semantics.
• The DbfOctet methods convert to/from a string of the form "0xXX"
• The DbfBoolean get method supports all the choices specified in the DBD Record Instance Specification
• For DbfArray to and from must be an array of one of DbfInt16, ..., DbfFloat64