Revision as of 13:22, 9 June 2005

EPICS: dbdClasses - IOC record

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

`dbfTypes.h`

    enum dbfType {
        dbfUnknownT,
        dbfTypeBoolean,     // epicsBoolean
        dbfTypeOctet,       // epicsOctet
        dbfTypeInt16,       // epicsInt16
        dbfTypeInt32,       // epicsInt32
        dbfTypeInt64,       // epicsInt64
        dbfTypeFloat32,     // epicsFloat32
        dbfTypeFloat64,     // epicsFloat64
        dbfTypeString,      // EpicsString
        dbfTypeArray,       // DbfArray
        dbfTypeMDArray      // DbfMDArray
        dbfMenuT,           // DbfMenu
        dbfEnumT,           // DbfEnum
        dbfLinkT,           // DbfLink
        dbfDeviceT          // DbfDevice
        dbfTypeStruct,      // DbfStruct
    };

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.

DBD type

bool,...,string all become an epicsType , i.e. epicsBoolean,...EpicsString
array becomes a DbfArray or DbfMDArray.
struct becomes a DbfStruct
menu becomes DbfMenu
enum becomes DbfEnum
link becomes DbfLink
device becomes DbfDevice

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(fint,int16)
        ...
        field(ffloat,float64)
        field(fstring,string)
        field(array,array(double[])
        field(mdarray,array(double[,])
        field(fmenu,menu(name))
        field(fenum,enum)
        field(flink,link(in))
        field(fdevice,link(in,analogIO))
        field(displayLimits,struct(displayLimits))
    }

Then the generated header file will be

    class xxxRecord : public iocRecord {
    public:
        epicsBoolean fbool;
        epicsOctet   foctet;
        epicsInt16   fint;
        ...
        epicsFloat64 ffloat;
        EpicsString  fstring;
        DbfArray     array;
        DbfMDArray   mdarray;
        DbfMenu      fmenu;
        DbfEnum      fenum;
        DbfLink      flink;
        DbfDevice    fdevice;
        DbfStruct    displayLimits;
   };

epicsTypes

DbfMenu

DbfMenu is described as:

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

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

DbfEnum

DbfEnum is described as:

    class DbfEnum{
    public:
        epicsInt16  index;
        DbfArray  *pfield; //EpicsArray of epicsTypeString
    };

pfield is the address of a field in the same record that is a DbfArray of type EpicsString. It contains the choices.

DbfLink and DbdDevice

DbfLink is described as

    enum LinkDir {
        LinkDirNone,
        LinkDirForward,
        LinkDirIn,
        LinkDirOut,
        LinkDirInOut
    };
   
    class DbfLink{ 
    public:
        LinkDir   dir;
        DbdLink   *plinkDef;
        DbfStruct dataStruct;
    };
   
    class DbfDevice{
    public:
        LinkDir   dir;
        DbdDevice *pDbdDevice;
        DbfStruct dataStruct;
    };

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.

Link support always implements interface DbdLinkSupport

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.

DbfStruct

DbfStruct is described as

    class DbfStruct {
    public:
        DbdStruct *pdescription;
        void      *pstorage;
    };

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`

    class Interface {}; // Must be an interface, i.e. pure abstract class

    class DbdMenu{
    public:
        NODE        node; // for DbdMenuList
        EpicsString name;
        epicsInt16  nchoices;
        EpicsString *pchoice[];
    };
   
    class DbdLink{ //describes dbd link statement
    public:
        NODE         node; // For DbdLinkList
        LinkDir      dir;
        EpicsString  choiceName;
        EpicsString  dataStructName;
        DbdLinkSupport  *pinterface;
    };
   
    class DbdDevice { //describes dbd device statement
    public:
        NODE        node; // For linkList
        LinkDir     dir;
        EpicsString choiceName;
        EpicsString dataStructName;
        EpicsString interfaceName;
        Interface   *pinterface;
    };

    // Beginning of definitions for DbdStruct
    class DbdFieldAttribute {
    public:
        EpicsString  default;
        epicsBoolean readonly;
        epicsBoolean design;
        epicsBoolean special;
        epicsBoolean dynamic;
        epicsInt16   asl;
    };

    struct DbdStringDefaults { // defaults for string
        const char *bufferType;
        epicsInt32 capacity;
    };

    struct DbdArrayDefaults { // defaults for array
        dbfType    type;
        const char *bufferType;
        epicsInt32 capacity;
        epicsInt32 nelements;
    };

    struct DbdMDArrayDefaults { // defaults for mdarray
        dbfType  type;
        epicsInt16 ndim
        const char *bufferType;
        epicsInt32 capacity;
    };

    struct DbdStructDefaults { // defaults for struct
        DbdStructDescription *pdescription;
    };

    class DbdStructField {
    public:
        const char *name;
        epicsType   type;
        union {
            DbdStringDefaults  *pstring;
            DbdArrayDefaults   *parray;
            DbdMDArrayDefaults *pmdarray;
            DbdStructDefaults  *pstruct;
        } defaults;
        dbfType           type;
        DbdFieldAttribute attribute;
    };

    class DbdStruct{
    public:
        NODE             node; // for DbdStructList
        const char       *name;
        epicsInt16       nfields;
        DbdStructField   *pafield;//ptr to array of DbdStructField
    };

    class DbdRecord : public EpicsStructDef { // describes a record
    public:
        NODE              node; // for DbdRecordList
        LIST              instanceList;
        DbdStruct         dbdStruct; // for the fields in the record
        DbdRecordSupport  *psupport;
    };
   
    class DbdUserField{ // describes a dbd userField statement
    public:
        NODE   node; // For DbdUserFieldList
        EpicsString choiceName;
        epicsType   type;
        EpicsString dataStructName;
        DbdUserFieldHandler *pinterface;
    };
   
    // The following describes a record instance
    class DbdUserFieldInstance {
    public:
        NODE         node; // for DbdRecordInstance.userField
        EpicsString  name; // field name
        DbdUserField *pDbdUserField;
        void         *pstorage; // for DbdUserField.type
        EpicsStruct  dataStruct;
    };
   
    class DbdRecordInstance {
    public:
        NODE         node; // for DbdRecord.instanceList
        DbfStruct    dbfStruct;
        void         *pstorage;
        EpicsString  name;
        LIST         userField; // of DbdUserFieldInstance
    };
   
   
    class DbdStructList {
    public:
        LIST list;
    };
   
    class DbdRecordList {
    public:
        LIST list;
    };
   
    class DbdMenuList {
    public:
        LIST list;
    };
   
    class DbdLinkList {
    public:
        LIST list;
    };
   
    class DbdDeviceList {
    public:
        LIST list;
    };
   
    class DbdUserFieldList {
    public:
        LIST list;
    };

Discussion of dbdStatements

struct and record

The following classes describe the fields in a dbd struct or record definition: DbdStruct, DbdRecord, DbdField,and DbdFieldAttribute

The fields of DbdStruct are:

name: The name of the struct.
plifetime: The address of an implementation of interface DbdStructLifetime. The implementation is automatically generated from the dbd struct. See below for a description of the Lifetime methods.
nfields: The number of fields, e.g. fields in the structure.
pafields: pointer to an array of DbdField.
node: A node for the list of struct definitions

The fields of DbdRecord are;

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 Lifetime methods.
nfields: The number of fields, e.g. fields in the record.
pafields: pointer to an array of DbdField.
node: A node for the list of record definitions
node: This is a node for DbdRecordList
instanceList: The list of record instances of this record type.
psupport: The address of the DbdRecordSupport for this record type.

The fields of DbdField are:

name: The name of the field
type: The epicsType, which is always epicsTypeUnknown
dbftype: The dbfType of the field.
attribute: DbdFieldAttribute for the field

The fields of DbdFieldAttribute are:

default: An EpicsString providing a default value for the field.
readonly: Is the field readonly?
design: Is the field a design fields for DCTs?
special: Should DbdRecordSupport:special be called if the field is modified.
dynamic: Can the field change because of record processing?
asl: The access security level.

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 connects a DbdLink to a DbfLink instance.
dataStructName: The class name of an EpicsStruct for the Interface implementation
pinterface: The address of the DbdLinkSupport Interface implementation.

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 to a DbfDevice instance.
dataStructName: The class name of an EpicsStruct for the Interface implementation
interfaceName: The name of the interface type implemented by the device support
pinterface: The address of the Interface implementation.

User Defined Fields

Each dbd userField definition has an associated class DbdUserField with fields:

node: This is a node for DbdUserFieldList
choiceName: The name that matches a DbdUserField to a DbdUserFieldInstance
type: The epicsType for the user field
dataStructName: The class name of an EpicsStruct for the DbdUserFieldHandler
pinterface: The address of the DbdUserFieldHandler implementation.

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, i.e. the psuedo field name
pDbdUserField: The DbdUserField that describes the field
pstorage: Address of storage for the dbfType.
dataStruct: An EpicsStruct that holds the private data for the DbdUserFieldHandler.

The fields of DbdRecordInstance are:

pstructDef: address of the DbdRecord describing the record
pstorage
address of the storage for the record instance
node: A node for list DbdRecord.instanceList
name: The name of the record instance
userField: A DbdUserFieldInstance list for the record instance.

Lists

The following provide lists of various things:

DbdStructList: The list of each struct definition
DbdRecordList: The list of each record type definition
DbdMenuList: The list of each menu definition
DbdLinkList: The list of each link definition
DbdDeviceList: The list of each device definition
DbdUserFieldList: The list of each userField definition

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 DbdFieldPutString {
    virtual void primitive(EpicsString *pfrom, epicsType type,
                              void *pstorage) = 0;
    virtual void string(EpicsString *pfrom,
                              EpicsString *pEpicsString) = 0;
    virtual void array(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 EpicsStruct or DbfStruct fields
// An DbdStructLifetime interface is automatically generated.
class DbdStructLifetime : public EpicsStructLifetime {
public:
    virtual bool initialize(DbfStruct *pDbfStruct) = 0;
    virtual bool finalize(DbfStruct *pDbfStruct) = 0;
};

// For record definitions a DbdRecordLifetime is automatically generated.
class DbdRecordLifetime : public EpicsStructLifetime{
public:
    virtual bool initialize(DbdRecordInstance *pDbdRecordInstance) = 0;
    virtual bool finalize(DbdRecordInstance *pDbdRecordInstance) = 0;
};

// link support modules implement the following interface
class DbdLinkSupport {
public:
    virtual void report(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(EpicsString *errorMessage,
                    iocRecord *precord, DbffLink *pdbfLink) = 0;
    virtual bool get(EpicsString *errorMessage,
                    iocRecord *precord, DbffLink *pdbfLink,
                    epicsType type, void *pfield) = 0;
    virtual bool put(EpicsString *errorMessage,
                     iocRecord *precord, DbfLink *pdbfLink,
                     epicsType 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 bool process(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

`DbdFieldPutString`

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

primitive: This convert a string to one of the types: epicsBoolT, ..., <epicsTypeFloat64
string: Copies a string from pfrom to pEpicsString.
array: Accepts a string that has the DBD array initialization syntax, locates the string value for each element and calls either EpicsString:primitive or EpicsString:string 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 primitive, string, or array 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:primitive or EpicsString:string 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 from the dbd definition.

DbdStructLifetime and DbdRecordLifetime each has the following fields:

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

`DbdLinkSupport`

This is the interface implemented by the support associated with each DBD link.

DbdLinkSupport has the following methods:

report: generate a report about the link instance
initialize: perform initialization but do not connect
finalize: undo initialization. It is assumed that disconnect has already been called.
connect: connect to external source of data
disconnect: disconnect from external source of data
get: get a value from the external source. type specified the field type and pfield is the address of where to store the data.
put: put a value from the external source. type specified the field type and pfield is the address of where to obtain the data.

`DbdRecordSupport`

This is the interface implemented by each record support module. DbdRecordSupport has the following methods:

initBuffers: This is called during record initialization. It is responsible for creating the buffers associated with each string and array field. It may call associated support to do the initialization.
initConnections: This is called to connect to external sources. It may call associated support to make the connections.
breakConnections: This is called to disconnect to external sources. It may call associated support to break the connections.
process: Process the record.
special: This is called whenever an external source modifies a field with attribute special set to true.

`DbdUserFieldHandler`

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

DbdUserFieldHandler has the following fields:

initialize: Initialize the user field.
finalize: undo what was done during initialization
process: Called near the end of record processing just before monitors are handled.

Device Support Interfaces

Multiple interface definitions for device support will be defined. Record Support and device support must agree on which interface type is used for communication.

Anonymous

Search

Difference between revisions of "V4 Design: dbdClass"