V4 Design: dbdClass

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

EPICS: C++ class definitions for Database Definition

May 18 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:

  • epicsTypes.h - A set of primitive types that are part of base/src/libCom
  • dbdTypes.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.

epicsTypes

epicsTypes.h

epicsTypes.h defines a set of primitive tupes. It is used because the C99 standard does not define the exact number of bits for the primitive data types. It only defines the minimum number of bits.

In addition two extra types are defined:

  • epicsUnknownT - Unknown
  • epicsOctetT - An 8 bit byte.

epicsTypes.h contains the following: 

enum epicsType {
    epicsUnknownT,
    epicsBooleanT,
    epicsOctetT,
    epicsInt16T,
    epicsUInt16T,
    epicsInt32T,
    epicsUInt32T,
    epicsInt64T,
    epicsUInt64T,
    epicsFloat32T,
    epicsFloat64T,
};

/* some of the following may require OSD definitions*/
typedef bool               epicsBoolean;
typedef char               epicsOctet;
typedef short              epicsInt16;
typedef unsigned short     epicsUInt16;
typedef int                epicsInt32;
typedef unsigned int       epicsUInt32;
typedef long long          epicsInt64;
typedef unsigned long long epicsUInt64;
typedef float              epicsFloat32;
typedef double             epicsFloat64;

Discussion of epicsTypes

Each epicsType maps to a C++ primitive type. It may be necessary to provide operating system dependent definitions for some of the types. For example on some architectures a epicsInt64 may have to be defined as a long rather than a long long.

epicsTypeUnknownT is reserved for unknown types and will normally be caused by a configuration error.

dbdTypes

File dbdTypes.h describes types and classes related to dbd struct or record field definitions. The following naming conventions are used:

dbf
A primitive field type
Dbf
any class starting with Dbf describes a non-primitive struct or record field. For example DbfString describes a field(name,string).
*Dbd*
A class name that has Dbd imbeded in it describes something directly related to a dbd statement. For example LinkDbdSupport describes a dbd link definition.

dbdTypes.h

enum dbfType {
    dbfUnknownT = epicsUnknownT,
    dbfBooleanT = epicsBooleanT,
    dbfOctetT = epicsOctetT,
    dbfInt16T = epicsInt16T,
    dbfUInt16T = epicsUInt16T,
    dbfInt32T = epicsInt32T,
    dbfUInt32T = epicsUInt32T,
    dbfInt64T = epicsInt64T,
    dbfUInt64T = epicsUInt64T,
    dbfFloat32T = epicsFloat32T,
    dbfFloat64T = epicsFloat64T,
    dbfStringT,
    dbfStructT,
    dbfArrayT,
    dbfEnumT,
    dbfMenuT,
    dbfLinkT,
    dbfDeviceT
};

typedef epicsBoolean  dbfBoolean;
typedef epicsOctet    dbfOctet;
typedef epicsInt16    dbfInt16;
typedef epicsUInt16   dbfUInt16;
typedef epicsInt32    dbfInt32;
typedef epicsUInt32   dbfUInt32;
typedef epicsInt64    dbfInt64;
typedef epicsUInt64   dbfUInt64;
typedef epicsFloat32  dbfFloat32;
typedef epicsFloat64  dbfFloat64;

// StructDbd is base class for classes implementing struct
class StructDbd {};
// The following are described  in dbdStatements.h
class StructDbdDef; //describes a dbd struct definition
class MenuDbdDef; //describes a dbd menu definition
class LinkDbd;    //describes dbd link statement
class DeviceDbd;  //describes dbd device statement

/*DbfString holds UTF-8 characters*/
class DbfString {
public:
    dbfInt32  capacity;  /*capacity in bytes*/
    dbfBoolean isCharString;
    dbfOctet  *pstorage;
};

class DbfStruct{
public:
    StructDbdDef *pstructDef;
    StructDbd    *pstorage;
};

class DbfArray {
public:
    dbfInt32  capacity;  /*capacity in number of elements*/
    dbfInt32  size;      /*current number of elements*/
    dbfType   type; // can be dbfBooleanT, ..., dbfArrayT
    void      *pstorage; // aligned on natural boundary
};

class DbfMenu{
public:
    dbfInt16    index;
    MenuDbdDef  *pmenuDef; /* address of global menu */
};

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

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

class DbfLink{ 
public:
    LinkDir   dir;
    LinkDbd   *plinkDef;
    DbfStruct dataStruct;
};

class DbfDevice{
public:
    LinkDir   dir;
    DeviceDbd *pdeviceDef;
    DbfStruct dataStruct;
};

Discussion of dbdTypes

Primitive Types

The primitive types, all map directly to an epicsType.

If a record is defined as: 

    record(xxx) extends iocRecord {
        ...
        field(fbool,bool)
        field(foctet,octet)
        ...
        field(ffloat64,float64)
        ...
    }

Then the generated header file will be 

    class xxxRecord : public iocRecord {
    public:
        dbfBoolean fbool;
        dbfOctet   foctet;
        ...
        dbfFloat64 ffloat64;
        ...
   };

DbfString

DbfString is described as: 

    class DbfString {
    public:
        dbfInt32  capacity;  /*capacity in bytes*/
        dbfBoolean isCharString;
        dbfOctet  *pstorage;
    };

If a record definition contains 

    field(sfield,string)

Then the generated header file contains 

    DbfString sfield;
capacity
the the number of bytes referenced by pstorage NOT the number of characters.
isCharString
false if the current string can not be converted to a char

array, i.e. it can only be converted to a wchar_t array.

pstorage
the address of a UTF-8 null terminated character string.

An interface DbfStringSupport is defined to support DbfString.

DbfStruct

DbfStruct> is described as: 

    class DbfStruct{
    public:
        StructDbdDef *pstructDef;
        StructDbd    *pstorage;
    };

If a record definition contains 

    field(sstruct,struct(name))

Then the generated header file contains 

    DbfStruct sfield;

pstorage is the address of storage for the structure and pstructDef is the address of a description of the structure. StructDbdDef is described in dbdStatatements.h

Note that given a dbdStruct it is possible to locate both the address and description of the associated structure.

DbfArray

A DbfArray describes a 1-dim array of a single dbfType. Multi dimensional array can be constructed since a DbfArray can be a 1 dim array of DbfArray.

pstorage is guaranteed to be allocated on a natural boundary for dbfType.


DbfMenu

DbfMenu> is described as: 

    class DbfMenu{
    public:
        dbfInt16    index;
        MenuDbfDef  *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:
        dbfInt16  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;
        LinkDbd   *plinkDef;
        DbfStruct 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 LinkDbd 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 LinkDbd.
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 LinkDbdSupport

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 LinkDbdSupport, the device support implements an interface that both record support and device support understand.


dbdStatements

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

dbdStatements.h

// FieldDbdPtr is the address of storage for a dbfType
typedef void *FieldDbdPtr;

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

class StructFieldAttribute {
    DbfString  default;
    dbfBoolean readonly;
    dbfBoolean design;
    dbfBoolean special;
    dbfBoolean dynamic;
    epicsInt16 asl;
};

class StructDbdField {
public:
    DbfString name;
    dbfType   type;
    StructFieldAttribute *pattribute;
};

class StructDbdDef{
public:
    DbfString    name;
    Interface    *plifetime; // references a StructDbdLifetime
    dbfInt16     nfields;
    StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
};

class MenuDbdDef{
public:
    DbfString name;
    dbfInt16  nchoices;
    DbfString *pchoice[];
};

class LinkDbd{ //describes dbd link statement
public:
    LinkDir    dir;
    DbfString  choiceName;
    DbfString  dataStructName;
    Interface  *pinterface;
};

class DeviceDbd { //describes dbd device statement
public:
    LinkDir   dir;
    DbfString interfaceName;
    DbfString choiceName;
    DbfString dataStructName;
    Interface *pinterface;
};

// The following describes a record type
class RecordDbdDef { // describes a record type
    DbfString    name;
    Interface    *plifetime; // references a StructDbdLifetime
    dbfInt16     nfields;
    StructDbdField *pfield[]; // ptr to array of ptr to StructDbdField
};

// The following describes a record instance
class UserDbdField {
public:
    dbfString   name;
    dbfType     type;
    FieldDbdPtr pfield;
    InterfacePtr *pinterface; // references userFieldHandler
};

class RecordInstanceDef { // describes a record instance
    DbfString    name;
    RecordDbdDef *pRecordDbdDef;
    FieldDbdPtr  *precord;     // address of record instance
    UserDbdField *puserField[];
};


Discussion of dbdStatements

Struct

The Struct classes describe the fields in a dbd struct or record definition. The classes are : StructDbdDef, StructDbdField,and StructFieldAttribute

The fields of StructDbdDef are:

name
The name of the struct.
plifetime
The address of an implementation of interface StructDbdLifetime. The implementation is automatically generated from the dbd struct statement. See below for a description of the StructDbdLifetime methods.
nfields
The number of fields, e.g. fields in the structure.
pfields
pointer to an array of pointers to StructDbdField. Each StructDbdField contains the name and type of the fields.

The fields of StructDbdField are:

name
The name of the field
type
The dbfType for the field.
pattribute
The address of a StructFieldAttribute for the field

StructFieldAttribute has the attribute values for the field.

Menu

A dbd menu is described by class MenuDbdDef

The fields of MenuDbdDef are:

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

Link and Device

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

dir
The link direction
choiceName
The name that matches a LinkDbd 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 LinkDbdSupport

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

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

Record

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

name
The name of the record.
plifetime
The address of an implementation of interface StructDbdLifetime. The implementation is automatically generated from the dbd record statement. See below for a description of the StructDbdLifetime methods.
nfields
The number of fields, e.g. fields in the record.
pfields
pointer to an array of pointers to StructDbdField. Each StructDbdField contains the name and type of the fields.
puserField
Address of an array of pointers to UserDbdField.

Question? Is RecordDbdDef necessary? Might be good to keep it in case a difference between struct and record becomes necessary.

Record Instance

A record instance has two associated classes:UserDbdField and RecordInstanceDef.

UserDbdField contains information for a user defined field:

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 RecordInstanceDef are:

name
The name of the record instance
pRecordDbdDef
The address of the description of the record type
precord
The address of the record itself.
puserField
The address of a array of pointers to UserDbdField

dbdInterfaces

dbdInterfaces describes standard interfaces implemented by code that supports runtime database access. For some the code is automatically generated from the dbd definitions.

dbdInterfaces.h

dbdInterfaces.h contains the following: 

// every struct and every record support module implements the following
// The implementation is generated from the dbd definition
class StructDbdLifetime {
public:
    virtual StructDbdPtr create() = 0;
    virtual bool initialize(dbfString *errorMessage,
                             StructDbdPtr ptr) = 0;
    virtual bool finalize(dbfString *errorMessage,
                             StructDbdPtr ptr) = 0;
    virtual void destroy(StructDbdPtr ptr) = 0;
    virtual void *indexToAddr(dbfString *errorMessage,
                             StructDbdPtr ptr, dbfInt16 index) = 0;
    // ???? is anything else needed
};

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

/* record support implements the following*/
class RecordDbdSupport {
public:
    virtual iocRecord *create(dbfString *errorMessage) = 0;
    virtual bool destroy(dbfString *errorMessage, iocRecord *precord) = 0;
    virtual bool init(dbfString *errorMessage,
                     iocRecord *precord, bool firstPass) = 0;
    virtual void special(iocRecord *precord, iocRecord *precord,
            bool  after,
            dbfInt16 nlevels, // number of elements in fieldIndex
            dbfInt16 fieldIndex[] // array of field indices
            ) = 0;
};

class UserFieldHandler {
public:
    virtual bool initialize(dbfString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
    virtual bool finalize(dbfString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
    virtual bool process(dbfString *errorMessage,
                     iocRecord *precord,UserDbdField *puserField) = 0;
};

Discussion of dbdInterfaces

StructDbdLifetime

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

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

LinkDbdSupport

This describes the interface implemented by link support.

RecordDbdSupport

This is the interface implemented by record support.

UserFieldHandler

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



DbfStringSupport Interface

This describes a proposed interface to support DbfString.

The interface is "minimal" in that it provides only a basic set of methods. If code needs to do serious character manipulation it must:

  • Use toChar or toWcar to convert a DbfString to an array of char or wchar_t
  • Use standard library support to do character manipulation
  • Use fromChar or fromWChar to convert the result to a DbfString,

DbfString is defined as: 

    class DbfString {
    public:
        dbfInt32  capacity;  /*capacity in bytes*/
        dbfBoolean isCharString;
        dbfOctet  *pstorage;
    };
capacity
is the amount of storage in bytes allocated for pstorage
isCharString
Is true if the UTF_8 null terminated string can be converted

to a char array. It is false if a wchar_t is required.

pstorage
Is a null terminated UTF_8 encoded character string.

DbfStringSupport.h contains: 

    class DbfStringSupport {
        virtual bool allocate(DbfString *pstring, epicsInt32 capacity) = 0;
        virtual null free(DbfString *pstring) = 0;
        virtual bool isCharString(DbfString *pstring) = 0;
        virtual epicsInt32 length(DbfString *p) = 0;
        virtual epicsInt32 length(char *p,epicsInt32 maxsize) = 0;
        virtual epicsInt32 length(wchar_t *p,epicsInt32 maxsize) = 0;
        virtual bool isEqual(DbfString *p1st,DbfString *p2nd) = 0;
        virtual bool toChar(DbfString *pstring,DbfString error,
                    char *pcharstring, epicsInt32 maxsize) = 0;
        virtual bool fromChar(DbfString *pstring,
                    const char *pcharstring, epicsInt32 maxsize) = 0;
        virtual bool toWChar(DbfString *pstring,DbfString error,
                    wchar_t *pcharstring, epicsInt32 maxsize) = 0;
        virtual bool fromWChar(DbfString *pstring,
                    wchar_t *pcharstring) = 0;
    };
allocate
pstring.pstorage is set equal to the address of capacity bytes of memory. pstring.capacity is set equal to the number of bytes. pstorage MUST NEVER be allocated by any means other than calling allocate.
free
The storage referenced by pstring.pstorage is freed. pstring.capacity and pstring.pstorage are set to 0.
length(DbfString *p)
Returns the number of characters in the string.
length(char *p,epicsInt32 maxsize)
Returns the number of bytes required for a UTF_8 encoded string.
length(wchar_t *p,epicsInt32 maxsize)
Returns the number of bytes required for a UTF_8 encoded string.
isEqual
Performs a byte by byte comparison until a null byte is detected or capacity of either string is reached. It returns (false,true) if the strings (are not, are) equal.
toChar
Converts a DbfString to a null terminated C char array. A return of true means success. A return of false means failure and the reason is returned in error.  : Converts a null terminated C char array to a DbfString. If the current capacity of pstring is not sufficent, free and allocate are called automatically. A return of true means success. A return of false means failure and the reason is returned in error.
toWChar
Converts a DbfString to a null terminated C wchar_t array. A return of true means success. A return of false means failure and the reason is returned in error.  ; fromChar
fromWChar
Converts a null terminated C wchar_t array to a DbfString. The result is a UTF_8 encode string. If the current capacity of pstring is not sufficent, free and allocate are called automatically. A return of true means success. A return of false means failure and the reason is returned in error.


Questions:

  • Is one implementation of DbfStringSupport sufficient or is a separate implementation required for each locale?
  • Hopefully only one implementation is required. But then are the above arguments sufficient.


Example of Generated Header Files

Database Definition Files

menuAlarmSevr.dbd contains: 

    menu(menuAlarmSevr) { 
         choice(menuAlarmSevrNO_ALARM,"NO_ALARM") 
         choice(menuAlarmSevrMINOR,"MINOR")
         choice(menuAlarmSevrMAJOR,"MAJOR")
         choice(menuAlarmSevrINVALID,"INVALID")
    }

displayLimit.dbd contains: 

    struct(displayLimit) {
        field(low,float64)
        field(high,float64)
    }

exampleRecord.dbd contains: 

    record(example) extends iocRecord {
        field(value,float64)
        field(displayLimit,struct(displayLimit))
    }

alltypesRecord.dbd contains: 

    record(allTypes) extends iocRecord {
        field(fbool,bool)
        field(foctet,octet)
        field(fint16,int16)
        field(fuint16,uint16)
        field(fint32,int32)
        field(fuint32,uint32)
        field(fint64,int64)
        field(fuint64,uint64)
        field(ffloat32,float32)
        field(ffloat64,float64)
        field(fstring,string)
        field(fmenu,menu(menuName))
        field(fenum,enum(stateNames))
        field(stateNames,array(string[]))
        field(fstruct,struct(displayLimit))
        field(flink,link(dir))
        field(fdevice,device(dir,interfaceName))
    }

Generated Header Files

Tools are provided to generate header files from the following dbd definitions:

  • menu
  • struct
  • record

menuAlarmSevr.h is generated from menuAlarmSevr.dbd 

    enum menuAlarmSevr {
           menuAlarmSevrNO_ALARM,
           menuAlarmSevrMINOR,
           menuAlarmSevrMAJOR,
           menuAlarmSevrINVALID
    };

displayLimit.h is generated from displayLimit.dbd 

    class displayLimit : public StructDbd {
    public:
        dbfFloat64 low;
        dbfFloat64 high;
    };
    const dbfInt16 displayLimit_firstIndex = 1
    const dbfInt16 displayLimit_low        = 1
    const dbfInt16 displayLimit_high       = 2
    const dbfInt16 displayLimit_lastIndex =displayLimit_high

exampleRecord.h is generated from exampleRecord.dbd 

    class exampleRecord : public iocRecord{
    public:
        dbfFloat64 value;
        dbfStruct  displayLimit;
    };
   
    const dbfInt16 example_firstIndex = 1001001
    const dbfInt16 example_low = 1001001;
    const dbfInt16 example_high = 1001002;
    const dbfInt16 example_lastIndex = example_high;

alltypesRecord.h is generated from alltypesRecord.dbd 

    class allTypesRecord : public iocRecord{
    public:
        dbfBoolean fbool;
        dbfOctet   foctet;
        dbfInt16   fint16;
        dbfUInt16  fuint16;
        dbfInt32   fint32;
        dbfUInt32  fuint32;
        dbfInt64   fint32;
        dbfUInt64  fuint32;
        dbfFloat32 ffloat32;
        dbfFloat64 ffloat64;
        DbfString  fstring;
        DbfMenu    fmenu;
        DbfEnum    fenum
        DbfArray   stateStrings;
        DbfStruct  fstruct;
        DbfLink    flink;
        DbfDevice  fdevice;
    };
   
    const dbfInt16 allTypes_firstIndex = 1001001;
    const dbfInt16 allTypes_fbool = 1001001;
    const dbfInt16 allTypes_foctet = 1001002;
    const dbfInt16 allTypes_fint16 = 1001003;
    const dbfInt16 allTypes_fuint16 = 1001004;
    const dbfInt16 allTypes_fint32 = 1001005;
    const dbfInt16 allTypes_fuint32 = 1001006;
    const dbfInt16 allTypes_fint64 = 1001007;
    const dbfInt16 allTypes_fuint64 = 1001008;
    const dbfInt16 allTypes_ffloat32 = 1001009;
    const dbfInt16 allTypes_ffloatn64 = 10010010;
    const dbfInt16 allTypes_ffstring = 10010011;
    const dbfInt16 allTypes_fmenu = 10010012;
    const dbfInt16 allTypes_fenum = 10010013;
    const dbfInt16 allTypes_stateStrings = 10010014;
    const dbfInt16 allTypes_fstruct = 10010015;
    const dbfInt16 allTypes_flink = 10010016;
    const dbfInt16 allTypes_fdevice = 10010017;
    const dbfInt16 allTypes_lastIndex = allTypes_fdevice;
Retrieved from "https://wiki-ext.aps.anl.gov/epics/index.php?title=V4_Design:_dbdClass&oldid=193"