V4 Design: Runtime Interfaces

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

For most strings all the database needs is a nonmutable string. For these it wants to be able to pass a reference to it to arbitrary code. It needs this for things like record type names, field names, record instance names, menu choice names, etc. etc. Some of these may change but very infrequently. The string always contains UTF-8 encoded strings, which I believe can be printed with a "%s" format if the string is made available as a "const char *"

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. In this case the record support can do what ever it wants to handle the string. It can even just use C style strings!!!

Thus all the IOC database needs is a:

1) nonmutable reference counted continguous string. When the reference count goes to 0 the storage can be reclaimed 2) The ability to copy the value from a nonmutable string to a mutable string.

In Java String and StringBuffer are all that is needed.

In C++ all that is needed is

1) A class that holds UFT-8 encoded non-mutable strings and make the contents available as a "const char *" and it's length. The class keeps a reference count and frees the storage when done. 2) The ability to copy the nonmutable string to a "char *" array allocated by the requester.

That is all.

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,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.
• 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 Support

Link

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

Link is an interface that must be implemented by every link support. An instance of this is connected to each DbfLink 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 Link 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 modidied.

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

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

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

Process Link Support

    interface ProcessLinkSupport<type> {
        void process();
        LinkWaitResult processWait(double timeout,Callback callback);
    }

Monitor Link Support

There is support for the following types: octet, boolean, int16, int32, int64, float32, float64, and arrays of each of these types.

    interface MonitorLink<type> {
        void get(<type> data);
    }

Input Link Support

There is support for the following types: octet, boolean, int16, int32, int64, float32, float64, and arrays of each of these types.

    interface InputLinkSupport<type> {
        void get(<type> data);
        LinkWaitResult getWait(<type> data, double timeout,Callback callback);
    }

Output Link Support

There is support for the following types: octet, boolean, int16, int32, int64, float32, float64, and arrays of each of these types.

    interface OutputLinkSupport<type> {
        void put(Dbf field);
        LinkWaitResult putWait(Dbf field, double timeout,Callback callback);
    }

---

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

---