V4 Design: Record Processing

EPICS V4: Record Processing

August 17 2005

---

Overview

This version is based on feedback from the EPICS core developer's meeting at ANL/APS on July 11th through July 14th. It is also a companion to the V4 Design: dbdInterfaces wiki.

The 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 it must be posssible for a record to 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 must be 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.

---

V4 Link Semantics

Lets first state some goals for linking to other records:

NOTE: Instead of "forward link" the name "process link" is used.

The features described next apply to both database and channel access links.

• Input Link from another record
  • get current value
  • wait until next record process and get value
  • request process, wait, get value
• Output Link to another record
  • put value
  • put value and request process
  • put value, request process, wait
• process link to another record
  • request processing
  • request processing and wait
• all links to other records
  • Allow simultaneous requests, i.e. process and wait in parallel
  • process one link at a time, i.e. process and wait serially.

NOTE: wait does NOT mean to block. It means to save state, return, and resume at the saved state when called again.

---

V4 Processing States

Instead of the V3 PROC field, V4 will have a field processState. This field has the states:

processIdle

record is not being processed

processInputActive

waiting for input links to complete

processActive

record is waiting for completion of record specific activity

processOutputActive

waiting for output and process links to complete

processDone

process has completed.

NOTES:

• Each state may have substates. For example if a record has multiple input links that are to be processed sequentially, it can keep state describing which link is being processed.
• Individual record types might use only a subset of the above states.
• V3 link instances had attributes like CA, CP, CPP. For V4 these should be something like:
  • process - a request to process the record before gets or after puts.
  • wait - a request to wait until it has processed all it's input links
  • parallel - OK to allow simultaneous gets or puts

---

dbProcess

The functionality described in this section will be divided between iocCore and iocRecord. iocRecord is the V4 successor to the V3 dbCommon. For V4 it is a separate software component.

NOTE: FLNK (forward link) is replaced by an array of process links.

dbProcess implements a state machine that use processState as well a private state dbProcessState which has the following:

dbProcessIdle

record is not being processed

dbProcessIocRecord

iocRecord is in control

dbProcessRecordSupport

record support is in control

dbProcessDone

complete record processing

For each state the following actions are performed:

• dbProcessIdle
  • prepare record for processing and call iocRecord with processState = processIdle
  • If iocRecord returns processInputActive set dbProcessState = dbProcessIocRecord and return
  • If iocRecord returns processActive set processState = idle and goto state dbProcessRecordSupport
  • If iocRecord returns processDone goto state dbProcessDone
• dbProcessIocRecord
  • If processState = processInputActive call iocRecord
    • If iocRecord returns processInputActive return
    • If iocRecord returns processActive set processState = processIdle and goto state dbProcessRecordSupport
    • If iocRecord returns processDone goto state dbProcessDone
  • If processState = processDone or processOutputActive call iocRecord
    • If iocRecord returns processOutputActive return
    • If iocRecord returns processDone goto state dbProcessDone
• dbProcessRecordSupport
  • If processState = processIdle, processInputActive, or processActive call record support
    • If record support returns processInputActive return
    • If record support returns processActive handle monitors and return
    • If record support returns processDone goto dbProcessIocRecord
  • If processState = processDone or processOutputActive call record support
    • If record support returns processOutputActive return
    • If record support returns processDone goto dbProcessIocRecord
• dbProcessDone
  • Perform final processing - See below for details.
  • set dbProcessState = dbProcessIdle and processState = processIdle
  • return

The remaining subsections provide more details about each processState. Keep in mind that some actions are performed by dbProcess, some by iocRecord, some by record support, and some by link support.

processState processIdle

If dbProcess is called with dbProcessIdle and processIdle then it:

• Sets all dynamic monitor bits to 0
• Other stuff?????
• calls iocRecord with processState processIdle

When iocRecord is called with processState processIdle it:

• initializes severity. See Alarm Processing for details.
• initializes status. See Alarm Processing for details.
• starts processing it's input links. Details are given below.
• returns with processState one of the following:
  • processInputActive - dbProcess will again call iocRecord.
  • processActive - dbProcess will set processState to processIdle and call record support.
  • processDone - dbProcess will complete processing. record support will NOT be called and iocRecord will not be called to handle output links

When record support is called with processState processIdle it:

• starts processing it's input links. Details are given below.
• returns with processState one of the following:
  • processInputActive - dbProcess will again call record support
  • processActive - dbProcess will again call record support
  • processOutputActive - dbProcess will again call record support
  • processDone - dbProcess will call iocRecord to process it's output links

processState processInputActive

This state means that one or more input links to other records have not completed. Links can be processed in parallel, sequentially, or a combination of these. iocRecord handles the links in iocRecord and record support handles record specific input links. The support is responsible for implementing sequential or parallel link processing. It calls link support to do the actual I/O. The Link support methods provide options specifying if the linked record should be processed and provide a callback to call when link processing completes. It is up to iocRecord or record support to again call dbProcess when all input links complete.

If is OK for dbProcess to be called multiple times while input links are being processed. When iocRecord detects that all it's input links have completed, it sets processState = processActive and returns. dbProcess then sets processState = processIdle and calls record support so that it starts processing it's input links.

When record support is called it returns one of:

• processActive - dbProcess will again call record support
• processOutputActive - dbProcess will again call record support
• processDone - dbProcess will call iocRecord to process it's output links

processState processActive

This state means that record support and associated device support are waiting for something to complete, e.g. for a motor to reach some position.

The record, however, can be processed so that it can report intermediate data values, e.g. the current motor position. For example the record can be periodically scanned.

When record support detects that it is done, it sets the processState to either processOutputActive or processDone.

While the processState is processActive dbProcess will post dynamic monitors.

processState processOutputActive

This state means that one or more output links to other records have not completed. Links can be processed in parallel, sequencially, or a combination of these. Record support handles the record specific output links and then iocRecord handles the output and process links in iocRecord. When record support detects that all it's output links are done, it returns with processState processDone. dbProcess then calls iocRecord which starts processing it's output and process links. Until it is done it sets processState to processOutputActive. When it is done it sets the processState to processDone.

processState processDone

When both record support and iocRecord have reported that they are done, dbProcess does some final steps and then sets the processState to processIdle.

The final steps are:

• If the request to process the record included a callback, the callback is called.
• If other record completion callback requests are present, call them.
• Dynamic monitors are posted
• ???
• The processState is set to processIdle and dbProcessState to dbProcessIdle.

---

Mutual Exclusion

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

For V4 we should try to get rid of lock sets.

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 an 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 no longer valid.

For V4 dbProcess will not be called recursively. Instead a request will be made to process the record.

• If the link is a channel access link than channel access is used.
• If the link is a database link to a passive record then the following can be done
  • A request is made for one of the standard callback threads to process the record,
  • The priority will be taken from the priority field in iocRecord.

Note that if all linked records are passive and the same priority then all processing can occur without any context switches. The following occurs:

• A request is made to a thread to call dbProcess.
  • The request is put on a queue associated with the thread.
• Sometime later the request is dequeued and dbProcess is called.
  • For each link process request the request is put on the queue for the same thread
  • After all requests are queued dbProcess returns
• The thread takes each request off the queue and calls dbProcess for the associated linked record
  • When all linked records finish processing a request is queued to call dbProcess for the original record
• The request for the original record is removed from the queue and it's dbProcess is again called.
  • The record completes.

This leaves the question of what should be done about mutual exclusion? At least the following two locks per record instance are needed:

recordLock

This is locked when dbProcess is called and unlocked before dbProcess returns. It is entirely private to dbProcess. This prevents simultaneous calls to dbProcess.

fieldLock

This must be taken before accessing any field.

Should fieldLock be private to database access?

• yes - This simplifies code that accesses the database BUT it means that database access must lock/unlock every access of every field
• no - Any code can access multiple fields with just one lock/unlock.

Perhaps we should start with a private lock?

A problem remains: Array fields. As described below, array fields may only be accessable in segments. It might be a channel access client that is accessing the array in segments and will block between segments while waiting for the data to be transfered over the network.

How to prevent two clients from trying to access the same array simultaneously?

• Does it matter?
• If application wants to allow only single access let the apllication solve the problem
  • runControl records are one solution
  • Other solutions can be envisioned
• Conclusion is that this is not a database responsibility

---

get/put database fields

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

The semantics differ depending on the DbfType.

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

The index value is handled just like DbfInt16. Since the choices for a menu can't change, only the changes to the index can occur.

DbfEnum

The index value is handled just like DbfInt16.

The choices are handled as an array of strings. See array below for details.

DbfLink and DbfDevice

Both of these have the following:

• choiceName A string that selects the link or device support.
• dataStruct Each support has an associated struct for configuration.

How should the be made available? Perhaps:

The field appears as a string with the following syntax:

choiceName(structAssignmentList)

where structAssignmentList has the same syntax as defined in "V4 DB Record Instance Syntax"

timeStamp

This is just transfered a struct with two fields:

• int64 secondsSinceEpoch
• int32 nanoSeconds

struct

The database definition syntax allow a struct to be composed of fields of any DbfType. How should this be made available to clients?

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

One possibility is to just make each field a member of a synchronous set of data. This is probably not a good solution.

Another possibility is to make the following two forms of access available.

• Access by clients that have knowledge of the structure -
  • This access will only be implemented if all fields are either primitive or string.
  • In this case the data is transfered as a sequence of field values.
• Access by clients that do not know about the structure -
  • The structure value is presented as a string that has the structAssignmentList syntax defined in "V4 DB Record Instance Syntax"

array

• segmented memory - Database Access is implemented so that record/link/device 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.
• data type - The database definition syntax allow an array to be any of the basic types, i.e. DbfBool,...,DbfFloat64, DbfString, DbfArray, DbfStruct.
  • For primitive types, the data should be passed as a sequence of scalar values. Question? Should it be possible to pass a subarray, i.e. offset, length?
  • For DbfString it should also be possible to pass that array as a sequence of string values.
  • What about DbfArray? Perhaps this should not be supported?
  • What about DbfStruct?

MDArray

TBD

Associated Data

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

Perhaps these can be handled as four synchronized requests to the same record.

How is this implemented?

• What does dbProcess do?
• How does a client make the request

---

Posting Modifications

The document "V4 Design: dbdIterfaces" provides a design that allows dbAccess to detect all changes to fields of an IOC record.

dbAccess handles all posting on monitors without requiring any help from the code that modifies database fields.

The following is the initial attempt to describe how monitors are handled.

The following definitions are used:

• monitor - A client has asked to be notified when a field value changes.
• post - Create storage, copy the current value of the field into the storage, and pass the storage to the monitor subsystem.
• static database field - A field that changes only because something external to the record modifies the field.
• dynamic database field - A field that changes because of record processing.

Static and dynamic fields have different semantics for monitors.

static fields

• primitive types - This includes DbfBool, DbfOctet, DbfInt16, ..., DbfFloat64. When a static primitive field is modified, a monitor is immediately posted.
• DbfMenu - Whenever the index is modified, a monitor is immediately posted. Since the choices for a menu can't change, only the changes to the index can occur.
• DbfEnum - Whenever the index is modified, a monitor is immediately posted. What about when a choice changes?
  • Should only the choice that changes be posted? If so what is the syntax?
  • Should the complete new set of choices be posted?
  • Should the user just be notified that one or more choices changed and the user must issue a new read request?
• DbfLink and DbfDevice
  • Both of these have the following:
    • choiceName A string that selects the link or device support.
    • dataStruct Each support has an associated struct for configuration.
  • What should be made available?
    • Perhaps just notification that a change has occcured. Client must issue new read request
• string - Perhaps
  • When a static string field is modified, a monitor is immediately posted.
  • Is this correct? For long strings it could cause excessive amounts of memory to be consumed. Probably not a big problem.
• array - Memory becomes a big issue.
  • Perhaps the following semantics could be used.
    • The array is posted when the value changes.
    • When the value changes, the client is notified and must issue a read request to retrieve the data.
  • Should both or only one be supported? If both who decides which semantics to use?
    • client?
    • database developer?
    • ???
• struct -
  • Since structures can contain fields of any DbfType what to do???
    • Structure with only primitive or string fields should be posted immediately*** What about structures containing arrays or structures?
    • Any fields that are not a basic type should not be supported.

dynamic fields

For each dynamic database field, dbAccess keeps a modify bit that is set to 0 when the record starts processing and is set to 1 whenever the field is modified.

Whenever record support returns with processState processActive or iocRecord returns with processState processDone, then the following is done:

• The monitor subsystem is notified about the beginning of synchronized monitors.
• Each field with the associated bit set to 1 is posted.
• The associated bit is set back to 0.
• Since status, severity, and timeStamp are dynamic fields in iocRecord, they follow the same logic.
• The monitor subsystem is notified about the end of synchronized monitors.

Separate discussions are required for the following: 1) primitive fields, 2) string fields, 3) structured fields, and 4) array fields.

• primitive fields - No problems.
• string fields - Memory is an issue.
  • Should there be a way to postpone posting until the monitor is ready to retrieve the value?
  • If so who decides?
• struct fields - Memory is again an issue.
  • Structure with only primitive fields should be posted immediately but perhaps complicated structures should not be.
  • Who decides?
  • How?
• array fields - memory is an issue
  • It should be possible to post small arrays of primitive type.
  • Large arrays should not be posted until monitor system is ready to accept the data.
    • It should also be possible to just notify the client that the array changed but the client must issue a read request to retrieve the data.

---

Alarm Processing

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

• alarmSeverity has the same values as for V3
• status is independent of alarmSeverity, i.e. it just reports a status.
• 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 that implement these goals are:

• When a record starts processing the following is done
  • The status is saved in previousStatus
  • status is set to an empty string
  • The alarmSeverity is saved in previousAlarmSeverity
  • alarmSeverity is set to NO_ALARM
• When the status is modified
  • If the new status is different than previousStatus
    • previousStatus is set to the new status
    • the status modified bit is set
• When the alarmSeverity is modified
  • If the new alarmSeverity is different than previousAlarmSeverity
    • previousAlarmSeverity is set to the new alarmSeverity
    • the alarmSeverity modified bit is set
• When dynamic monitors are posted
  • If status != previousStatus the status modified bit is set
  • If alarmSeverity != previousAlarmSeverity the alarmSeverity modified bit is set
  • If the status modified bit is set the status is posted and previousStatus set equal to status
  • If the alarmSeverity modified bit is set the alarmSeverity is posted and previousAlarmSeverity set equal to alarmSeverity