V4 Design: Record Processing

EPICS V4: Record Processing November 02 2005

---

Overview

UNRESOLVED ISSUES

• This document is still evolving
• Monitors
  • How will monitor data be managed?
  • Big problem is how will array data be managed?
• Alarms
  • How will V4 handle alarms?
• Events
  • What is the V4 event model?
  • What is required from the IOC database?

This document described semantics for V4 record processing that are different than for V3. This includes the following:

• Semantics for record processing
• Semantics for Database and Channel Access Links.
• Record Locking
• Posting database monitors
• Status and Alarm Severity
• Access to array and structure fields.

This version is based on feedback from the EPICS core developer's meeting at ANL/APS on July 11th through July 14th. In addition discussions with Andrew Johnson and Eric Norum have led to many of the ideas described below. This wiki is a companion to the wiki "V4 Design: dbdInterfaces".

V3 record processing semantics do not work well for data acquisition applications. An example of data acquisition is:

• Move sample to new position.
  • Several motors may be involved
  • While moving post monitors to show current position, etc.
• Sample data
• Wait until CA client has fetched the data before next move.

SynAPPS provides the Scan, motor, etc records which help with data processing applications. These records process as follows:

• Record does not complete processing until all inputs, outputs, etc done. Not completing means that they do not call recGblFwdLink until all proccessing is complete. Note that recGblFwdLink is what causes the V3 ioc to complete record processing.
• While waiting for asynchronous events these records have PACT=0 but keep state that shows it is still active
• Can be scanned and issue monitors while internal state is active

Leaving PACT 0 but not calling recGblFwdLink was not anticipated when the V3 record processing semantics were created. For V4 a record can be processed while it is waiting for asynchronous processing to complete.

In V3, if an input link is asynchronous, Process Passive does not wait for asynchronous processing to complete before fetching data. This also complicated data acquisition applications.

V4 record processing is designed to make data acquisition easier. Both input and output links can wait for record processing. This is done, however, without record support blocking. If blocking makes it easier to implement record support, then the support can spawn a separate thread that does block. Record support can communicate with the separate thread to decide when to complete record processing.

---

Overview of V4 Record Processing

V4 will provide a replacement for dbProcess. The name may be different but for now it will still be called dbProcess.

In V4 database access and channel access appear the same to record and link support. Only the implementation knows the difference. In this document the term channelAccess will mean access to a record. Thus it can mean a workstation client or a field of a record that is a link to a record.

V4 also allows support for struct fields. For example base provides support for

    field(common,struct(RecordCommon))

In the record types provided with base, this is the first field. The fields in RecordCommon are the V4 replacement for the V3 dbCommon fields.

V4 record processing has the following features.

• database fields
  • "owned" by database not record support
  • fields can only be accessed via interfaces
  • support can optionally provide storage for data associated with a field
  • for channelAccess all fields appear as type primitive, string, struct, array or combination thereof
• dbProcess
  • processes synchronous linked records by queuing requests rather than recursive calls to dbProcess
  • can be called an arbitrary number of times while record is active
• link
  • always has associated support
  • can be record link or can be something else, e.g. a link to hardware
• record link
  • can request process and/or wait for asynchronous completion
  • local synchronous requests queued by dbProcess
  • record is active and can be processed while asynchronous links active
• struct fields
  • Can have associated support which can be synchronous or asynchronous
• block
  • is requested via a separate field
  • if true than support waits for all outstanding I/O to complete before further processing
  • if false than asynchronous support can proceed in parallel
• lock
  • record instances are locked
  • dbProcess locks before calling support
  • other code can also lock
  • Two records can be locked without deadlock
• monitors
  • dbProcess handles monitors
  • support triggers monitors by writing to fields

Database Fields

Field Access by Support Code

Support code can access database fields only via interfaces implemented by the IOC database. Thus record fields are owned by the IOC database not by record support.

Support code can register to provide storage for particular fields. For example support code could implement a circular buffer for field value. When some other code request the array associated with value, the IOC database calls the support. The support returns the first portion of the circular buffer and the caller must make an additional call to retrieve the rest of the circular buffer.

Field Access by Channel Access

For V4 database access and channel access appear the same to record instances. It is only the code that implements link support that knows the difference. If a linked record is local, database access is used, and, if the record is remote, channel access.

V4 allows channel access to the following types of fields:

• primitive types
• string
• one dimensional array of primitive or string or struct
• struct with fields of following types:
  • primitive
  • string
  • struct
  • array of primitive or string or struct

For other database field types, i.e. links, the database will make the field appear as one of the above types. For example a link field will appear as a string with syntax that matches the information associated with the link. For example a process link will have a string something like

   support(processLink) ProcessLink(pvname = 'pvname'; wait = true)

where

processLink

selects the support for a process link

ProcessLink

Names the struct that the support uses for configuration information

Record Processing Semantics

This section describes the semantics implemented by dbProcess.

The following are involved in record processing

• dbProcess
  • implements a queue for local records that are processed because of record links
  • posts monitors caused by field changes during record processing
• record support
  • calls support code for RecordCommon fields
  • is responsible for record instance fields
  • calls link/struct support via interfaces implemented by the support
• link support
  • can be links to other records, to driver support, etc
  • implements interfaces called by record and/or other support
• struct support
  • is responsible for the fields in the struct
  • implements interfaces called by record and/or other support

Processing Life Cycle

Assume a record instance is idle, i.e. is ready to start processing.

• dbProcess calls record support with one of the following states
  • processCancel - record support must terminate any outstanding processing
  • processStart - start processing. record support returns one of
    • processDone - All done and successful
    • processQuit - dont do any more processing. Return to idle state
    • processActive - not done. Call again
  • processContinue - another request to process while record is active. Record support again returns one of the above.

Record support, with associated link/struct support does the following:

• When it is called for processStart
  • calls the support for RecordCommon with state processStart. it returns
    • processDone - Record support starts processing record specific fields
    • processQuit - Record support just returns processQuit to dbProcess
    • processActive - Record returns processActive. It will be called again with state processContinue. It calls RecordCommon support with state processActive. This continues until Record Common returns processDone or processQuit
• When RecordCommon returns processDone record support starts processing record specific fields
  • Associated link or struct support may be called
    • Record support implements any block fields.
    • It detects when asynchronous support completes
    • as long as there is incomplete asynchronous support it returns processActive to dbProcess
  • When all record specific fields have been processed it calls RecordCommon suport with state processQuit
    • RecordCommon support can return processActive. Until it returns processDone, record support just returns processActive to dbProcess
  • When RecordCommon returns processDone, record support returns processDone to dbProcess.

struct and link fields can have associated support

• associated support may be asynchronous
  • support returns indicating that it is active
  • support is required to detect when asynchronous support completes
  • when processing is complete support returns indicating that it is done.
• whenever record support returns to dbProcess, dbProcess posts any fields that were modified.
  • record may be active or done
• when record support returns processDone or processQuit record is again set idle.

record common

These fields are optional but it is expected that most record types will include a standard set of fields.

The support for RecordCommon processes the following fields:

• at the beginning of record processing
  • disabled - if true NO processing will be done, i.e. processQuit is returned
  • scanDisable
    • has associated support
    • if record is scan disabled processQuit is returned
  • alarm fields
    • alarm handling is described below
• after record support completes
  • processLink array
    • has associated support

record support

Record support is responsible for all its fields. For link and struct fields there may be associated support which may be synchronous or asynchronous. Record support communicates with the link/struct support via interfaces that are implemented by the support. If the record includes a field for struct(RecordCommon) it should use the associated support for its fields.

Record support may be called multiple times by dbProcess while a record instance is active. One of the arguments to process is ProcessState which has the values:

• processCancel - Cancel any outstanding activity
• processStart - Start processing
• processContinue - Making additional call

process returns ProcessReturn which is one of the following:

• processDone - Done and successful
• processQuit - Do not do any more processing
• processActive - Not done

If record support returns processActive it must keep internal state so that it knows how to handle processCancel and processContinue.

For record support the above rules allow:

• process can be called repeatedly. This will continue as long as it returns processActive
• Everytime process returns processActive DbProcess posts monitors.

Record Locking

V3 implemented lock sets in order to prevent different threads from simultaneously accessing linked records.

Instead of lock sets V4:

• implements a per record instance lock.
• defines a rule that allows two records to be locked without deadlocks

Posting Monitors

In V3 monitors are posted when code (record support, device support, database access, etc) calls db_post_event. In V4 database access will itself handle the posting of monitors.

Monitors are posted by DbProcess when

• record support returns processActive.
• at the end of record processing.

link/struct Semantics

Both link and struct fields can have associated support. The support can be synchronous or asynchronous.

Support code implements interfaces. Code that is responsible for a field communicates with the support via the interface. Lets call this code the client.

Each link and struct field has a well defined client.

• The support for RecordCommon is the client for fields in dbCommon
• record support is the client for the other top level fields in a record
• the struct support is the client for any link or struct fields in the struct

A link/struct may have an associated block. The client is responsible for implementing block. If block is true then the support will not be called until all outstanding record activity completes.

channelAccess links

channelAccess link means access to a record or field. The requester can be:

• A database link in a record
• A channel access link in a record
• A workstation channel access client

A channelAccess link is one of the following types:

• Monitor Link
  • Implemented via a monitor request on linked field
  • Optionally process record containing the link when monitor value is returned.
• Input Link
  • Optionally request that record be processed.
  • Optionally wait for linked record to complete processing.
  • Get value.
• Output Link:
  • Put value
  • Optionally request processing.
  • Optionally wait until completion
• Process Link: Perform the following actions
  • Request processing
  • Optionally wait until linked record completes

NOTES:

• processLink is the replacement for the V3 forwardLink
• wait does NOT mean to wait synchronously. It means to save state, return, and resume at the saved state when called again.

Links are processed as follows:

The following rules apply when a process request is made:

• If record is already being processed the request is just ignored
• record support can specify that links to particular fields not cause processing.
  • Where should this be specified? In the Database Definition, the record instance, or both.
  • If a process request is allowed, should it be done regardless of the scan mechanism, i.e. the record does not have to be passive?

---

Mutual Exclusion

V3 implemented lock sets, i.e. when a record was being processed it and all records linked via database links were locked.

Lock sets solved two Mutual Exclusion problems:

• V3 allowed dbProcess to be called recursively.
  • process passive database links and forward links were implemented via recursive calls to DbProcess
  • Lock sets prevented deadly embrace problems for circular links.
• No puts could be done to a record in a lock set while record processing is active.
  • For synchronous records this guarantees that no fields are modified except by record processing itself.
  • For asynchronous records this guarantee is not valid.

V4 does not call dbProcess recursively. Instead a process request is queued. The request fails if either of the following is true:

• The record is active.
• The record is already queued.

dbProcess itself manages the queue , which is FIFO. When record support returns the first entry in the queue is processed. In addition if link or struct support completes before the queue is empty, a request to process the record containing the link/struct will be added to the same queue. Thus if a set of synchronous records are processed they will complete processing without any context switch.

Question What about periodically scanned records? Needs thought.

This leaves the question of what should be done about mutual exclusion.

For V4 there will be two locks associated with the IOC database: 1) a global lock, and 2) A per record instance lock.

The global lock must be taken whenever the structure of the database is modified. Examples are 1) adding new record types, 2) adding new record instances, and 3) modifying database links. Global locks are not discussed further in this document.

Each record instance has an associated lock. When dbProcess is called it takes the lock. Before it returns it unlocks. Thus record support does not need to lock or unlock.

Other code that needs access to fields of a record instance must lock before accessing any fields and unlock after all accesses are complete.

This leaves the problem of how to access fields from two different record instances simultaneously. For example code that implements database access needs such access. Code that needs such access must call dbLockLink before accessing the linked record and dbUnlockLink after access.

dbLockLink is implemented as follows:

• Each Record instances has a unique ordinal number
• Assume Record X has a link to record Y
• If the ordinal number of X is less than that of Y
  • Just call dbLock for record Y
• If the ordinal numnber of X is greater than that of Y
  • call dbUnlock for X
  • call dbLock for Y
  • call dbLock for X

---

Posting Modifications

The document "V4 Design: dbdIterfaces" provides a design that allows database access to handle all posting on monitors without requiring any help from the code that modifies database fields. It can do this because fields can be modified only via an interface implemented by database access.

dbProcess posts monitors when:

• When record support returns processActive.
• When it finishes record processing.

How to implement monitors must be decided.

---

Alarm Processing

Question Will V4 alarm handling be different than V3? If so this section may be meaningless.

The V4 semantics for status and severity have the following goals:

• alarmSeverity has the same values as for V3
• alarmStatus is a string
• a record starts processing with alarmSeverity = "NO_ALARM" and status empty.
• status will ONLY be posted if it has changed since the last time it was posted.
• alarmSeverity will ONLY be posted if it has changed since the last time it was posted

The semantics, which are implemented by the support for RecordCommon, are:

• When recordCommon is called with processStart
  • A private variable newSeverity is set to NO_ALARM
  • A private variable prevSeverity is set to alarmSeverity
• When recordCommon completes its part of record processing
  • If newSeverity is NO_ALARM and prevSeverity has a different value
    • alarmSeverity is set to NO_ALARM
    • alarmStatus is set to empty

• When the recordCommon.setSeverity(sevr,status) is called
  • If sevr is less than or equal to newSeverity nothing is done
  • else
    • alarmSeverity is set to sevr
    • alarmStatus is set to status
    • newSeverity is set to sevr

NOTE: alarmStatus and alarmSeverity are written by the normal method. This means that their values will be posted.

---

Channel Access/ Database Access field types

Overview

This section discusses how IOC database fields are accessed by channel access or via database links.

For the initial V4 implementation only the following types of data will be accessable.

• primitive types
• string
• enum
• one dimensional array of primitive or string or struct
• struct with fields of following types:
  • primitive
  • string
  • enum
  • struct (use recursion for allowed types)
  • one dimensional array of primitive or string or struct

The dbdInterfaces document defines database field types. It also defines a subset called basic types, which consists of primitive types, string, array, and structure. For external access only basic types can be accessed. This means that structures and arrays that do not consist of basic types are not accessablevia clannelAccess. For example a DbfLink is not accessable via channel access as a DbfLink.

Non basic fields will only be available via some combination of basic types.

For example a DbfLink field will appear as a string. If a Database Definition is

    struct(calcInpLink) {
        field(block,boolean)
        field(link,link)
        field(value,float64)
    };
    
    record(xxx) {
        field(link,link)
        field(value,float64)
    ...
        field(inp,array(struct(calcInpLink)[]))
    ...
    }

If a client attaches to

    record.field(link)

The data will be appear in the form:

    choice(choiceName) SupportStruct(pvname= ...)

where choiceName is the name of the link support, SupportStruct is the name of the support struct asociated with the support, and the arguments are the values for the support structure.

Then if a client specifies the process variable:

    record.field(inp[1].link)

Then it connects to the link field of the second calcInpLink of field inp.

primitive types

This includes DbfBool, DbfOctet, DbfInt16, ... , DbfFloat64. These do not present any problems. The scalar value is transfered.

string

A string is just a UTF_8 encoded character string

DbfMenu and DbfEnum

Handled as an enum

DbfLink

A string with the same syntax as defined for a link field in "V4 DB Record Instance Syntax"

timeStamp

This is just transfered like a struct with two fields:

• int64 secondsSinceEpoch
• int32 nanoSeconds

struct

The individual fields can be accessed directly so this discussion only involves access to the entire structure.

The entire structure can be accessed as a string with the same syntax as defined for a struct field in "V4 DB Record Instance Syntax"

array

Arrays of the following types are accessable:

• primitive - DbfBool,...,DbfFloat64
• DbfString
• DbfStruct - As long as its fields are valid types

Note that arrays of structs are not accessable in the early V4 releases.

Arrays still need lots more discussion!!! The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.

For the initial V4 version, database access only allows access to arrays of the following types.

• primitive - DbfBool,...,DbfFloat64
• DbfString
• ???? What else

An individual element of an array of type DbfStruct can be accessed directly if it satisfies the criteria for accessing a DbfStruct.

Question: Should database Access be implemented so that record/link support can transfer an array in segments. Examples:

• If the array is a circular buffer, it is presented in two segements
• If the array is stored in hardware, e.g. a transient recorder, the array can be read from the hardware and passed to the client in segments.

If an array is available only in segments then can we prevent two clients from trying to access the same array simultaneously?

Perhaps this is a problem that must be solved by an application:

• runControl records are one solution
• Other solutions can be envisioned

MDArray

Not implemented if the early V4 releases.

Associated Data

The typical example is a client that asks for timeStamp, severity, status, and data.