V4 Design: Runtime Interfaces

EPICS: IOC Runtime Interfaces September 23 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.

NOTE IOC runtime needs lots more work

---

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

This subsection describes interfaces for C++ code that needs tempory storage for strings. For Java the String class is used.

The following interfaces are for allocating tempory storage for strings:

    class NonmutableString {
    public:
       void destroy(); // Call this when done with string
       int32_t getLength();
       char data[];
    }
   
    class NonmutableStringFactory {
    public:
        static NonmutableString *create(int32_t len,char data[]);
    }

    class MutableString : public NonmutableString {
    public:
       int32_t getCapacity();
       void setLength(int32_t len);
    }
   
    class MutableStringFactory {
        static MutableString *create(int32_t capacity);
    }

These will use free lists to manage the storage for the octet arrays.

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

---

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

NOTE The V4 replacement for registerRecordDeviceDriver must call DisplayLimitAccessRegister.createAndRegister.

Similar files are generated for C++.

record definitions

If a record is defined as:

    record(Example) extends 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 {
        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++.

---

Record Support

    enum ProcessState {
        processCancel,
        processStart,
        processContinue,
    }

    enum ProcessReturn {
        processDone,
        processAbort,
        processActive
    }

    interface RecordSupport {
        void destroy();
        void initialize(int32 pass);
        ProcessState process(ProcessState state);
        // 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.
• 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
                }
            }
        ...
        }
    }

---

Link and Device Support

Link/Device Base

    interface Support { // base for Link and Device support
        void report(int16 level);
        void cancel();
        void destroy();
        void initialize();
        void connect();
        void disconnect();
    }

Support is the base class for all link and device support. An instance of this is connected to each DbfLink or DbfDevice field. The 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.

Normally record support does not need to call any of the Base Support methods since Database Access does this automatically. For example if a link or device 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 modidied.

Link Support

    enum LinkWaitResult {
        linkNoop,           // Nothing was done, e.g. link is null link
        linkDone,           // field was modified. No wait is necessary
        linkWaitSequential, // waiting. must processes links sequentially
        linkWaitParallel,   // waiting. parallel processing OK
    }

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

    interface LinkSupport extends Support {
        void get(Dbf field);
        LinkWaitResult getWait(Dbf field, double timeout,Callback callback);
        void put(Dbf field);
        LinkWaitResult putWait(Dbf field, double timeout,Callback callback);
        void process();
        LinkWaitResult processWait(double timeout,Callback callback);
    }

LinkSupport supports the following semantics:

• Input Link from another record
  • get current value independent of processing state.
  • Ask the record to process and wait for completion before fetching value.
  • wait until next time record processes then get value. No request is made to process the record.
• Output Link to another record
  • put value without requesting that record be processed.
  • put value then process record but don't wait for processing to complete.
  • put value, process record, and wait for completion
• process link to another record
  • request processing but do not wait for completion
  • request processing and wait for completion

The Wait methods all return LinkWaitResult.

Device Support

Other than that it must extend Support, nothing is defined for Device support in this document. It will be modeled after the V3 asynDriver support.

---

Registration and Instance Creation

    interface StructFactory {
        DbfStruct create();
    }

    interface RecordSupportFactory {
        RecordSupport create(RecordInstance instance);
    }

    interface SupportFactory {
        Support create(Dbf field);
    }

    interface RegisterSupport {
        structure(StructFactory create, string name);
        record(StructFactory create, string name);
        link(SupportFactory support,string name);
        device(SupportFactory support,string name);
        record(RecordSupportFactory support,string name);
    }

RegisterSupport is implemented by iocCore. Each struct DBD definition must register a StructFactory to create instances of the structure or record.

Each link, device, and record support must register a SupportFactory to create instances of the support to attach to the link, device, or record instance. During database initialization, iocCore calls the factory methods.

---

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 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(DbInstance instance);
        RecordSupport getRecordCommonSupport(DbInstance instance);
    }

The methods are:

• 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

---