V4 Design: dbdClass

From EPICSWIKI
Revision as of 18:00, 31 May 2005 by MartyKraimer (talk | contribs)

EPICS: dbdClasses - IOC record

May 27 2005

Overview

This document describes the C++ class definitions for code that implements the semantics for records created from Database Definitions. The definitions are intended for code that:

  • includes header files generated from dbd definitions. Header files are generated from the following dbd definitions:
    • record - Should only be included by record support.
    • struct - Included by code that understands the struct.
    • menu - Included by code that understands the menu.
  • does not include the header files.

The following headers files are described:

  • dbfTypes.h - Type definitions for field definitions in struct or record> DBD definitions.
  • dbdStatements.h - Type definitions for DBD statements.
  • dbdInterfaces.h - Type definitions for interfaces related to DBD definitions.

dbfTypes

File dbfTypes.h describes types and classes that are used in header files generated from dbd struct or record field definitions. The following naming conventions are used:

Dbf
any class starting with Dbf describes a field in a generated header file. For example DbfString describes a field generated from field(name,string).
Dbd
A class name starting with Dbd describes something related to dbd definitions. For example DbdLinkSupport describes a dbd link definition.

dbdTypes.h

enum dbfType {
    dbfUnknownT,
    dbfEpicsT,  // an epicsType except epicsUnknownT
    dbfArrayT,
    dbfStructT,
    dbfMenuT,
    dbfEnumT,
    dbfLinkT,
    dbfDeviceT
};

class DbdStruct; //describes a dbd struct definition
class DbdMenu; //describes a dbd menu definition
class DbdLink;    //describes dbd link statement
class DbdDevice;  //describes dbd device statement

class DbfArray : public EpicsArray {
public:
    dbfType dbftype;
};

// Just like EpicsStruct but EpicsStructDef is DbdStructDef
class DbfStruct : EpicsStruct {
public:
};

class DbfMenu{
public:
    epicsInt16 index;
    DbdMenu    *pmenuDef; /* address of global menu */
};

class DbfEnum{
public:
    epicsInt16 index;
    EpicsArray *pchoiceArray; // addr of field that is array of string
};

enum LinkDir {
    LinkDirNone,
    LinkDirForward,
    LinkDirIn,
    LinkDirOut,
    LinkDirInOut
};

class DbfLink{ 
public:
    LinkDir   dir;
    DbdLink   *plinkDef;
    EpicsStruct dataStruct;
};

class DbfDevice{
public:
    LinkDir   dir;
    DbdDevice *pDbdDevice;
    EpicsStruct dataStruct;
};

Discussion of dbfTypes

The classes defined in dbfTypes together with the definitions from epicsTypes is a complete list of the definitions that appear in header files generated from struct and record dbd definitions.

Epics Types

DBD types bool,...,string all become an epicsType.

DBD type array becomes an EpicsArray if the array type maps to an epicsType or to DbfArray if the type is not an epicsType.

DBD type struct maps to EpicsStruct if all fields in the struct map to an epicsType or otherwise to DbfStruct.

If a record is defined as: 

    struct(displayLimits) {
        field(low,double)
        field(high,double)
    }
    record(xxx) extends iocRecord {
        ...
        field(fbool,bool)
        field(foctet,octet)
        ...
        field(ffloat64,float64)
        ...
        field(fstring,string)
        field(darray,array(double[])
        field(displayLimits,struct(displayLimits))
    }

Then the generated header file will be 

    class xxxRecord : public iocRecord {
    public:
        epicsBoolean fbool;
        epicsOctet   foctet;
        ...
        epicsFloat64 ffloat64;
        ...
        EpicsString  fstring;
        EpicsArray   darray;
        EpicsStruct  displayLimits;
   };

DbfArray

This is for array fields with a type that is not a standard epicsType.

If a record definition contains: 

    struct(calcInpLink) {
        field(link,link(in))       // NOT a standard epicsType
        field(value,float64)
    }
    record(calc) extends iocRecord {
        ...
        field(inp,array(struct(calcInpLink)[]))
        ...
    }

Then the generated code contains: 

    DbfArray inp;

DbfStruct

This is for a struct field that itself has fields that are not a standard epicsType, i.e. the epicsType is epicsUnknownT.

If a record definition contains: 

    struct(calcInpLink) {
        field(link,link(in))     // NOT a standard epicsType
        field(value,float64)
    }
    record(calc) extends iocRecord {
        ...
        field(inp,struct(calcInpLink))
        ...
    }

Then the generated code contains: 

    DbfArray inp;

DbfMenu

DbfMenu is described as: 

    class DbfMenu{
    public:
        epicsInt16    index;
        DbdMenu  *pmenuDef;
    };

If a record definition contains 

    field(fmenu,menu(name))

Then the generated header file contains 

    DbfMenu fmenu;

DbfMenu provides the current menu index and also the menu definition.

DbfEnum

DbfEnum is described as: 

    class DbfEnum{
    public:
        epicsInt16  index;
        DbfArray  *pchoiceArray; // addr of field that is DbfArray on choices
    };

If a record definition contains 

    field(fenum,enum)

Then the generated header file contains 

    DbfEnum fenum;

pchoiceArray is the address of a field in the same record that is a DbfArray of choices.

DbfLink

DbfLink is described as 

    class DbfLink{ 
    public:
        LinkDir   dir;
        DbdLink   *plinkDef;
        EpicsStruct dataStruct;
    };

If a record definition contains 

    field(flink,link(in))

Then the generated header file contains 

    DbfLink flink;

The fields of DbfLink are initialized by locating a dbd link definition that matches the dir specified in the dbd field definition.

The fields of DbfLink are initialized as follows:

dir
This is taken from either the field definition or from the DbdLink definition and is the most restrictive. For example if one says inout and the other says in then dir will be in.
plinkDef
This is the address of the DbdLink.
dataStruct
The describes the data structure specified in the dbd link definition. It contains data used by the link support.

Note that link support always implements interface DbdLinkSupport

DbfDevice

A DbfDevice is similar to a DbfLink except that the interface implemented by the device support is also specified, i.e. instead of implementing interface DbdLinkSupport, the device support implements an interface that both record support and device support understand.


dbdStatements

The definitions in dbdStatements.h allow introspection of ioc records. They describe everything defined in DBD definitions.

NODE and LIST specify a doubly linked list. An implementation is not specified.

dbdStatements.h

// Interface is base class for an interface
class Interface {};
class InterfaceLocator {
public:
    EpicsString name;
    Interface *pinterface;
};

class DbdStructFieldAttribute {
public:
    EpicsString  default;
    epicsBoolean readonly;
    epicsBoolean design;
    epicsBoolean special;
    epicsBoolean dynamic;
    epicsInt16 asl;
};

class DbdStructField : EpicsStructField {
public:
    dbfType     dbftype;
    DbdStructFieldAttribute attribute;
};

// Like EpicsStructDef but DbdStructField extends EpicsStructField
class DbdStructDef : EpicsStructDef{
public:
    NODE              node; // for DbdStructDefList
};

class DbdMenu{
public:
    EpicsString name;
    epicsInt16  nchoices;
    EpicsString *pchoice[];
};

class DbdLink{ //describes dbd link statement
public:
    NODE         node; // For DbdLinkList.linkList
    LinkDir      dir;
    EpicsString  choiceName;
    EpicsString  dataStructName;
    DbdLinkSupport  *pinterface;
};

class DbdDevice { //describes dbd device statement
public:
    NODE        node; // For linkList.deviceList
    LinkDir     dir;
    EpicsString choiceName;
    EpicsString dataStructName;
    EpicsString interfaceName;
    Interface   *pinterface;
};

class DbdUserField{ // describes a dbd userField statement
public:
    NODE   node; // For DbdUserFieldList
    EpicsString choiceName;
    epicsType   type;
    EpicsString dataStructName;
};

// The following describes a record type
class DbdRecordDef : extends EpicsStructDef { // describes a record type
public:
    NODE              node; // for DbdRecordList.recordType
    LIST              instanceList;
    DbdRecordSupport  *psupport;
};

// The following describes a record instance
class DbdUserFieldInstance {
public:
    NODE         node; // for DbdRecordInstance.userField
    EpicsString  name; // field name
    DbdUserField *pDbdUserField;
    DbdUserFieldHandler *pinterface;
    void         *pstorage; // for DbdUserField.type
    EpicsStruct  dataStruct;
};

class DbdRecordInstance { // describes a record instance
public:
    NODE         node; // for DbdRecord.instanceList;
    EpicsString  name;
    DbdRecordDef *pDbdRecordDef;
    void         *precord;     // address of record instance
    LIST         userField; // of DbdUserFieldInstance
};



class DbdStructDefList {
public:
    LIST structType;
};

class DbdRecordDefList {
public:
    LIST recordType;
};

class DbdLinkList {
public:
    LIST linkList;
};

class DbdDeviceList {
public:
    LIST deviceList;
};

class DbdUserFieldList {
public:
    LIST userFieldList;
};


Discussion of dbdStatements

DbdStruct

The DbdStruct classes describe the fields in a dbd struct or record definition. The classes are : DbdStruct, DbdStructField,and DbdStructFieldAttribute

The fields of DbdStruct are:

name
The name of the struct.
plifetime
The address of an implementation of interface StructLifetime or DbdRecordLifetime. The implementation is automatically generated from the dbd struct or <record> statement. See below for a description of the Lifetime methods.
nfields
The number of fields, e.g. fields in the structure.
pfields
pointer to an array of pointers to DbdStructField.

The fields of DbdStructField are:

name
The name of the field
basic
The epicsType of the field. Unless this is epicsUnknownT generic code is usually provided for accessing the field.
type
The dbfType for the field. Unless basic is epicsUnknownT this has the value dbfEpicsT.
attribute
An DbdStructFieldAttribute for the field

DbdStructFieldAttribute has the attribute values for the field.

Menu

A dbd menu is described by class DbdMenu

The fields of DbdMenu are:

name
The menu name.
nchoices
The number of menu choices.
pchoice
The address of an array of pointers to EpicsString. Each EpicsString is a choice.

Link

Each dbd link definition has an associated class DbdLink with fields:

node
This is a node for DbdLinkList
dir
The link direction
choiceName
The name that matches a DbdLink for a DbfLink instance.
dataStructName
The class name of a DbfStruct for the Interface implementation
pinterface
The address of the Interface implementation. The interface class is DbdLinkSupport

Device

Each dbd device definition has an associated class DbdDevice with fields:

node
This is a node for DbdDeviceList
dir
The link direction
choiceName
The name that matches a DbdDevice for a DbfDevice instance.
dataStructName
The class name of a DbfStruct for the Interface implementation
interfaceName
The name of the interface class implemented by the device support
pinterface
The address of the Interface implementation.

Record

A record type has an associated class: DbdRecord. The fields of DbdRecord are the same as fields in DbdStruct except that they refer to a record instead of a structure.

node
This is a node for DbdRecordList
instanceList
The list of record instances of this record type.
name
The name of the record type.
plifetime
The address of an implementation of interface DbdRecordLifetime. The implementation is automatically generated from the dbd record statement. See below for a description of the RecordLifetime methods.
psupport
The address of the DbdRecordSupport for this record type.
nfields
The number of fields, e.g. fields in the record.
pfields
pointer to an array of pointers to DbdStructField. Each DbdStructField contains the name and type of the fields.


Record Instance

A record instance has two associated classes:DbdUserFieldInstance and DbdRecordInstance.

DbdUserFieldInstance contains information for a user defined field:

node
A node for list DbdRecordInstance.userField
name
The name of the user defined field
type
The dbfType for the field.
pfield
Address of storage for field.
pinterface
The address of an implementation of interface userFieldHandler;

The fields of DbdRecordInstance are:

node
A node for list DbdRecord.instanceList
name
The name of the record instance
pDbdRecord
The address of the description of the record type
precord
The address of the storage for the record instance.
userField
A DbdUserFieldInstance list for the record instance.

DbdStructList

A list of all the struct definitions. The nodes are described by DbdStructNode which has fields:

node
The node for the list.
isEpicsType
determines if the structure is a EpicsStructDef or a DbdStruct
pdef
The address of the EpicsStructDef or Db that describes the structure.

DbdRecordList

The list of record types

DbdLinkList

List of DbdLink

DbdDeviceList

List of DbdDevice

dbdInterfaces

dbdInterfaces describes standard interfaces implemented by code that supports runtime database access.

dbdInterfaces.h

dbdInterfaces.h contains the following: 

// The following is implemented by database access
class DbdRecordEpicsFieldPutString {
    virtual void epicsPrimitive(EpicsString *pfrom, epicsType type,
                              void *pstorage) = 0;
    virtual void epicsString(EpicsString *pfrom,
                              EpicsString *pEpicsString) = 0;
    virtual void epicsArray(EpicsString *pfrom,
                              EpicsArray *pEpicsArray) = 0;
    virtual void epicsStruct(EpicsString *pfrom,
                              EpicsStruct *pEpicsStruct) = 0;
    virtual void epicsMDArray(EpicsString *pfrom,
                              EpicsMDArray *pEpicsMDArray) = 0;
}

// For struct definitions that become DbfStruct fields
// An DbdStructLifetime interface is automatically generated.
class DbdStructLifetime {
public:
    virtual void allocate(DbfStruct *pDbfStruct) = 0;
    virtual bool initialize(DbfStruct *pDbfStruct) = 0;
    virtual bool finalize(DbfStruct *pDbfStruct) = 0;
    virtual void destroy(DbfStruct *pDbfStruct) = 0;
    virtual void *expose(DbfStruct *pDbfStruct, epicsInt16 index) = 0;
};

// For record definitions an DbdRecordLifetime is automatically generated.
class DbdRecordLifetime {
public:
    virtual void allocate(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool initialize(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool finalize(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void destroy(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void *expose(DbdRecordInstance *pDbdRecordInstance) = 0;
};

// every link support module implements the following interface
class DbdLinkSupport {
public:
    virtual void report(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool initialize(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool finalize(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool connect(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink) = 0;
    virtual bool disconnect(epicsfString *errorMessage,
                     iocRecord *precord, DbffLink *pdbfLink) = 0;
    virtual bool get(EpicsString *errorMessage,
                     iocRecord *precord, DbffLink *pdbfLink,
                     dbfType type, void *pfield) = 0;
    virtual bool put(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink,
                     dbfType type, void *pfield) = 0;
};

/* record support implements the following*/
class DbdRecordSupport {
public:
    virtual bool initBuffers(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool initConnections(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool breakConnections(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual void special(DbdRecordInstance *pDbdRecordInstance,
            bool  after,
            epicsInt16 nlevels, // number of elements in fieldIndex
            epicsInt16 fieldIndex[] // array of field indices
            ) = 0;
};

class DbdUserFieldHandler {
public:
    virtual bool initialize(EpicsString *errorMessage,
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
    virtual bool finalize(EpicsString *errorMessage,
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
    virtual bool process(EpicsString *errorMessage,
                     iocRecord *precord,DbdUserFieldInstance *puserField) = 0;
};

Discussion of dbdInterfaces

DbdRecordEpicsFieldPutString

This is an interface, which has an implementation provided by iocCore, that convert an EpicsString to an epicsType. The methods are:

epicsPrimitive
This convert a string to one of the types: epicsBoolT, ..., <epicsFloat64T
epicsString
Copies a string from pfrom to pEpicsString.
epicsArray
Accepts a string that has the DBD array initialization syntax, locates the string value for each element and calls either EpicsString:epicsPrimitive or EpicsString:epicsString to convert the value and put it into the correct element of EpicsArray
epicsStruct
Accepts a string that has the DBD struct initialialization syntax, locates the string value associated with each field and calls epicsPrimitive, epicsString, or epicsArray to convert the value and put the result of the correct field of EpicsStruct The structure must not contain any unknown field types.
epicsMDArray
Accepts a string that has the DBD array initialization syntax, locates the string value for each element and calls either EpicsString:epicsPrimitive or EpicsString:epicsString to convert the value and put it into the correct element of EpicsMDArray

DbdStructLifetime and DbdRecordLifetime

Every dbd struct and record has an associated Lifetime interface implementation. A tool is provided that automatically generates the implementation form the dbd definition.

Lifetime has the following fields:

allocate
Creates storage for the struct or record.
initialize
initializes the struct or record
finalize
cleans up but does not free storage
destroy
frees storage
expose
Given an index it returns the address of the storage. Note the the generated header files assign an index to each field.

DbdLinkSupport

This describes the interface implemented by link support.

DbdRecordSupport

This is the interface implemented by record support.

UserFieldHandler

This is the interface implemented by code for user extensible fields.

Retrieved from "https://wiki-ext.aps.anl.gov/epics/index.php?title=V4_Design:_dbdClass&oldid=232"