Difference between revisions of "V4 Design: Record Processing"

From EPICSWIKI
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
= EPICS V4: Record Processing =
EPICS V4: Record Processing November 02 2005  
September 15 2005  


----
----


<center>
= Overview =
== Overview ==
</center>


<b>UNRESOLVED ISSUES</b>
<b>UNRESOLVED ISSUES</b>
* Monitored data: What are the semantics for monitors that involve large amounts of memory?
* 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
This document described semantics for V4 record processing that are
different than for V3.
different than for V3.
This includes the following:
This includes the following:
* Semantics for record processing
* Semantics for Database and Channel Access Links.
* Semantics for Database and Channel Access Links.
* Semantics for record processing
* Record Locking
* Record Locking
* Posting database monitors
* Posting database monitors
Line 61: Line 66:


<center>
<center>
== Goals for V4 Record Processing ==
= Overview of V4 Record Processing =
  </center>
  </center>


V4 record processing has the following features not available in V3:
V4 will provide a replacement for dbProcess.
The name may be different but for now it will still be called dbProcess.


* Links to other records:
In V4 database access and channel access appear the same to record and
** Can request that the linked record be processed. In V3 this was only available for puts and only if recordtype set pp(TRUE).
link support.
** Can wait until the linked record completes processing. In V3 this was only possible for puts.
Only the implementation knows the difference.
* While record support is active a record can still be processed and post monitors.
In this document the term channelAccess will mean access to a record.
* Database links are processed via queue requests rather than recursive calls to dbProcess.
Thus it can mean a workstation client or a field of
* Instead of lock sets, each record instance has a lock.
a record that is a link to a record.
* Monitors are implemented by database access without help from record support
* Channel Access and Database Access can access structures


=== Link Semantics ===
V4 also allows support for <b>struct</b> 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 <tt>RecordCommon</tt> are the V4 replacement for
the V3 dbCommon fields.


The link semanics are similar for database and channel access links (
input, output, and process).
All provide the ability to request processing and to wait until processing completes.


=== Processing Database Links ===
V4 record processing has the following features.


In V3 records linked via database links are processed via recursive calls to
* database fields
dbProcess. In V4 this will no longer be done. For V4 the following is done
** "owned" by database not record support
when a link requests processing:
** 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


# If the record is active or already queued the request fails.
# If the record does not allow link requests to cause processing the request fails.
# If neither 1) or 2) are true than the record is queued for processing.


<center>
= Database Fields =
</center>
== 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.


=== Record Locking ===
Support code can register to provide storage for particular fields.
 
For example support code could implement a circular buffer for field <tt>value</tt>.
V3 implemented lock sets in order to prevent different threads
When some other code
from simultaneously accessing linked records.
request the array associated with <tt>value</tt>, the IOC database
 
calls the support. The support returns the first portion of the circular
Instead of lock sets V4:
buffer and the caller must make an additional call to retrieve the rest of
* Implements a per record instance lock.
the circular buffer.
* 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.


== Field Access by Channel Access ==


=== Database Field Types ===
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 and Database Access to the
V4 allows channel access to the following types of fields:
following types of fields:


* primitive types
* primitive types
Line 125: Line 155:
** array of primitive or string or 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
; <tt>processLink</tt>
: selects the support for a process link
; <tt>ProcessLink</tt>
: Names the struct that the support uses for configuration information


<center>
== Link Semantics ==
</center>
NOTES:
* Link just 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 channel access client PV.
* Instead of "forward link" the name "process link" is used.
Links are processed as follows:
* Input Link: Two flavors are available
** Monitor Link
*** Implemented via a monitor request on linked field
*** Optionally process record containing the link when monitor value is returned.
** Input Link: Perform the following actions
*** Optionally request that record be processed.
*** Optionally wait for record to complete processing.
*** Get value.
* Output Link: Two varieties are available
**Output Only: Perform the following actions
*** Put value
*** Optionally wait until the put completes
** Output and Process: Perform the following actions
*** Put value and request that record be processed. Note that if record can not be processed the value is not changed.
*** Optionally wait until the put and process completes
* Process Link: Perform the following actions
** request processing
** Optionally wait until record completes processing.


The following rules apply when a process request is made:
* If record is already being processed the request fails.
* Record support can specify that links to particular fields not cause processing.
* A record can declare that it can not be processed via process links.
** This can be specified in the Database Definition or the record instance.
* If a process request is allowed, it will be done regardless of the scan mechanism, i.e. the record does not have to be passive.
NOTES For Record links:
* wait does NOT mean to block. It means to save state, return, and resume at the saved state when called again.
* When a record has multiple input links the links can be processed in parallel or sequentially
* When a record has multiple output links the links can be processed in parallel or sequentially
----
<center>
<center>
== Record Processing ==
= Record Processing Semantics =
  </center>
  </center>


This section describes the semantics implemented by dbProcess.
This section describes the semantics implemented by dbProcess.


dbProcess maintains a variable processState which is passed to iocRecord
The following are involved in record processing
and to record support and can also be returned by them.
* 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


== V4 Processing States ==
== 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.


processState is passed to process (iocRecord or record support) and is also
Record support, with associated link/struct support does the following:
returned by process.  processState defines the states:
* When it is called for processStart
; processCancel
** calls the support for RecordCommon with state processStart. it returns
: If record support is called with this state, it must terminate outstanding processing and prepare for being called with processIdle.
*** processDone - Record support starts processing record specific fields
; processIdle
*** processQuit - Record support just returns processQuit to dbProcess
: record is not being processed
*** 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
; processStart
* When RecordCommon returns processDone record support starts processing record specific fields
: processing is starting
** Associated link or struct support may be called
; processInputActive
*** Record support implements any <tt>block</tt> fields.
: iocRecord is waiting for input links to complete
*** It detects when asynchronous support completes
; processActive
*** as long as there is incomplete asynchronous support it returns processActive to dbProcess
: record support is waiting for completion of record specific activity
** When all record specific fields have been processed it calls RecordCommon suport with state processQuit
; processOutputActive
*** RecordCommon support can return processActive. Until it returns processDone, record support just returns processActive to dbProcess
: iocRecord is waiting for output and process links to complete
** When RecordCommon returns processDone, record support returns processDone to dbProcess.
; processDone
: process has completed.


NOTES:
* Record support can implement substates. For example the sequence record keeps state about which link set it is processing.
* Individual record types might use only a subset of the above states.
* V3 link instances had attributes like CA, CP, CPP. For V4 these are:
** 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


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.


== 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.
== record common ==


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


When dbProcess is called the action it takes depends on processState.
The support for RecordCommon processes the following fields:
* processCancel
** If iocRecord is active it is called with state processCancel
** If record support is active it is called with state processCancel
** prepare for state processIdle
* processIdle
** prepare the record for processing
** set state = processStart and goto processInputActive
* processInputActive
** call iocRecord
*** If iocRecord returns processInputActive return
*** If iocRecord returns processActive set processState = processStart and goto processActive
*** If iocRecord returns processDone goto processDone
* processActive
** Call record support
*** If record support returns processActive post monitors and return
*** If record support returns processDone goto processOutputActive
* processOutputActive
** Call iocRecord
*** If iocRecord returns processOutputActive return
*** If iocRecord returns processDone goto processDone
* processDone
** Perform final processing - See below for details.
** set processState = processIdle
** return


NOTES:
* at the beginning of record processing
* Record support is called with state processStart or processActive. It can return processActive as often as it wants. This supports the semantics of both the motor and sequence records.
** disabled - if true NO processing will be done, i.e. processQuit is returned
* The semantics support the following model
** scanDisable
** iocRecord processes all its input links and then
*** has associated support
** Record support stays active as long as desired and then
*** if record is scan disabled processQuit is returned
** iocRecord processes all its output links and then
** alarm fields
** dbProcess does final processing and sets the record idle.
*** alarm handling is described below
* after record support completes
** processLink array
*** has associated support


== record support ==


The remaining subsections provide more details about each processState. Keep in mind
Record support is responsible for all its fields.
that some actions are performed by dbProcess, some by iocRecord,
For link and struct fields there may be associated support which
some by record support, and some by link support.
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.


=== processState processCancel ===
Record support may be called multiple times by dbProcess while a record instance
When process (Record Support or iocRecord) is called with this state
is active.
it just prepares for being called again with state processIdle.
One of the arguments to process is ProcessState which has the values:
* processCancel - Cancel any outstanding activity
* processStart - Start processing
* processContinue - Making additional call


An example of when process is called with this state is when a Channel Access
process returns ProcessReturn which is one of the following:
request is made to modify a link or device field in a record instance that is not idle. If this happens, record support and/or iocRecord will be called
* processDone - Done and successful
to cancel any outstanding internal state.
* processQuit - Do not do any more processing
Process does not have to call link or device support because Database Access
* processActive - Not done
will call the cancel method of any link or device support attached to
the record.
=== processState processIdle ===
When dbProcess is called with processIdle it:
* prepares record for processing
* calls iocRecord with processStart


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


When iocRecord is called with processStart it:
* prepares for alarmStatus and alarmSeverity. See Alarm Processing for details.
* starts processing it's input links. Details are given below.
* returns with processState one of the following:
** processInputActive - dbProcess returns and when called again calls iocRecord.
** processActive - dbProcess calls record support with processStart.
** processDone - dbProcess completes processing. record support will NOT be called and iocRecord will not be called to handle output links


When record support is called with processStart it:
For record support the above rules allow:
* starts processing
* process can be called repeatedly. This will continue as long as it returns processActive
* returns with processState one of the following:
* Everytime process returns processActive DbProcess posts monitors.
** processActive - dbProcess returns and when called again calls record support.
** processDone - dbProcess calls iocRecord with processDone.


=== processState processInputActive ===  
== Record Locking ==


Only iocRecord is called with or returns this state.
V3 implemented lock sets in order to prevent different threads
from simultaneously accessing linked records.


This state means that one or more input links handled by iocRecord have not
Instead of lock sets V4:
completed.
* implements a per record instance lock.
* defines a rule that allows two records to be locked without deadlocks


When iocRecord detects that all it's input
== Posting Monitors ==
links have completed, it sets processState = processActive and returns.
dbProcess calls record support to start processing.


iocRecord can also return processDone, In this case dbProcess will just
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
do final cleanup and set state back to processIdle. This is done,
the posting of monitors.
for example if iocRecord finds the record disabled.


=== processState processActive ===
Monitors are posted by DbProcess when
* record support returns processActive.
* at the end of record processing.


Only record support is called with this state.
<center>
iocRecord and record support can return this state.
= link/struct Semantics =
</center>


This state means that record support and associated device support
Both link and struct fields can have associated support.
are waiting for something to complete. Examples are:
The support can be synchronous or asynchronous.
* wait for links to complete
* wait for a motor to reach some position.


The record, however, can be processed so that it can
Support code implements interfaces.
report intermediate data values, e.g. the current motor position.
Code that is responsible for a field communicates with the support via
For example the record can be periodically scanned.
the interface. Lets call this code the client.


When record support is called it returns one of:
Each link and struct field has a well defined client.
* processActive - dbProcess post monitors and returns. When it is called again it calls record support.
* The support for RecordCommon is the client for fields in dbCommon
* processDone - dbProcess calls iocRecord with processDone.
* 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


=== processState processOutputActive ===
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.


Only iocRecord is called with or returns this state.
<center>
= channelAccess links =
</center>


This state means that one or more output links handled by iocRecord have not
channelAccess link means access to a record or field. The requester can be:
completed.
* A database link in a record
* A channel access link in a record
* A workstation channel access client


iocRecord returns either
A channelAccess link is one of the following types:
* processOutputActive - record support returns and when called again calls iocRecord with processOutputActive.
* Monitor Link
* processDone - dbProcess does final processing as described next.
** 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.


=== processState processDone ===
Links are processed as follows:


Only iocRecord is called with or returns this state.
The following rules apply when a process request is made:
 
* If record is already being processed the request is just ignored
When iocRecord is called with processDone it starts processing its output links.
* record support can specify that links to particular fields not cause processing.
It returns either
** Where should this be specified?  In the Database Definition, the record instance, or both.
* processOutputActive - record support returns and when called again calls iocRecord with processOutputActive.
** 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?
* processDone - dbProcess does final processing as described next.
 
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.
* post monitors
* The record is set idle.
 
=== Links to Other Records ===
 
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.
Link support performs 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 links
are being processed.


----
----
<center>
<center>
== Mutual Exclusion ==
= Mutual Exclusion =
  </center>
  </center>


Line 375: Line 358:
Lock sets solved two Mutual Exclusion problems:
Lock sets solved two Mutual Exclusion problems:
* V3 allowed dbProcess to be called recursively.
* V3 allowed dbProcess to be called recursively.
** process passive database links and forward links were implemented via recursive calls to dbProcess
** process passive database links and forward links were implemented via recursive calls to DbProcess
** Lock sets prevented deadly embrace problems for circular links.
** 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.
* 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 synchronous records this guarantees that no fields are modified except by record processing itself.
** For asynchronous records this guarantee is not valid.
** For asynchronous records this guarantee is not valid.
Line 387: Line 370:
* The record is already queued.
* The record is already queued.


Queuing requests to process rather than recursively calling dbProcess
dbProcess itself manages the queue , which is FIFO.
does not necessarily cause unnecessary context switches.
When record support returns the first entry in the queue is processed.
For example if all linked records are passive and the same priority then
In addition if link or struct support completes before the queue
all processing can occur without any context switches.
is empty, a request to process the record containing the link/struct will
* A request is made to a thread to call dbProcess.
be added to the same queue.
** The request is put on a queue associated with the thread.
Thus if a set of synchronous records are processed they will complete processing
* Sometime later the request is dequeued and dbProcess is called.
without any context switch.
** For each link, with a request to 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.
<b>Question</b> What about periodically scanned records? Needs thought.
<b>Question</b> What about periodically scanned records? Needs thought.


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


Each record instance has an associated lock maintained by dbAccess.
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.
When dbProcess is called it takes the lock.
Before it returns it unlocks.
Before it returns it unlocks.
Thus iocRecord and record support do not need to lock or unlock.
Thus record support does not need to lock or unlock.


Other code that needs access to fields of a record instance must call
Other code that needs access to fields of a record instance must
dbLock before accessing any fields and dbUnlock after all accesses are complete.
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
This leaves the problem of how to access fields from two different record
Line 428: Line 414:
----
----
<center>
<center>
== Posting Modifications ==
= Posting Modifications =
  </center>
  </center>


Line 436: Line 422:
It can do this because fields can be modified only via an
It can do this because fields can be modified only via an
interface implemented by database access.
interface implemented by database access.
Fields are modified in one of two ways:
* Changes made while record is being processed. For these posting is handled by dbProcess.
* Changes by other code. For these posting is handled by dbLock/dbUnlock.
Each field of a record instance has two associated "modified" bits.
One is for changes handled by dbProcess. The other is for changes made
by dbLock/dbUnlock.


dbProcess posts monitors when:
dbProcess posts monitors when:
Line 450: Line 427:
* When it finishes record processing.
* When it finishes record processing.


 
How to implement monitors must be decided.
Other code can only change fields between calls to dbLock/dbUnlock
* When dbLock is called all its modify bits are false.
* Each field modification causes the associated modify bit to be set true.
* When dbUnlock is called it
** posts all fields that have changed
** sets the associated modify bits false
 
The following is the initial attempt to describe how monitors are implemented.
 
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.
 
Separate discussions is required for the following: 1) primitive fields,
2) string fields, 3) structured fields, and  4) array fields.
 
The following are just some thoughts.
 
* 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 field or string should be posted immediately but what about array fields?
** 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.
 
In any case the way monitors are posted must take into consideration
the views defined in the database definition for each record.


----
----
<center>
<center>
== Alarm Processing ==
= Alarm Processing =
  </center>
  </center>
<b>Question</b> 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:
The V4 semantics for status and severity have the following goals:
Line 497: Line 444:
* alarmSeverity 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 iocRecord, are:
The semantics, which are implemented by the support for RecordCommon, are:


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


* When the iocRecord.setSeverity(sevr,status) is called
* When the recordCommon.setSeverity(sevr,status) is called
** If sevr is less than or equal to newSeverity nothing is done
** If sevr is less than or equal to newSeverity nothing is done
** else
** else
Line 518: Line 465:
----
----
<center>
<center>
== Channel Access/ Database Access field types ==
= Channel Access/ Database Access field types =
  </center>
  </center>




=== Overview ===
== Overview ==


This section discusses how IOC database fields are accessed by channel access
This section discusses how IOC database fields are accessed by channel access
Line 546: Line 493:
For external access only basic types can be accessed.
For external access only basic types can be accessed.
This means that structures and arrays that do not consist of basic types
This means that structures and arrays that do not consist of basic types
are not accessable outside the record. For example a DbfLink is
are not accessablevia clannelAccess. For example a DbfLink is
not accessable via channel access as a DbfLink.
not accessable via channel access as a DbfLink.


Line 555: Line 502:


     struct(calcInpLink) {
     struct(calcInpLink) {
         field(link,link(in))
        field(block,boolean)
         field(link,link)
         field(value,float64)
         field(value,float64)
     };
     };
      
      
     record(xxx) {
     record(xxx) {
         field(link,link(in))
         field(link,link)
         field(value,float64)
         field(value,float64)
     ...
     ...
Line 570: Line 518:
     record.field(link)
     record.field(link)
The data will be appear in the form:
The data will be appear in the form:
     choiceName(pvname,...)
     choice(choiceName) SupportStruct(pvname= ...)
where <tt>choiceName</tt> is the name of the link support and the arguments
where <tt>choiceName</tt> is the name of the link support, <tt>SupportStruct</tt> is the name of the support struct asociated with the support, and the arguments are the values for the support structure.
are the values of the dataStruct associated with the support.


Then if a client specifies the process variable:
Then if a client specifies the process variable:
Line 579: Line 526:




=== primitive types ===
== primitive types ==


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


=== string ===
== string ==


A string is just a UTF_8 encoded character string
A string is just a UTF_8 encoded character string


=== DbfMenu  and DbfEnum ===
== DbfMenu  and DbfEnum ==


Handled as an enum
Handled as an enum




=== DbfLink and DbfDevice ===
== DbfLink ==


Both of these have the following:
A string with the same syntax as defined for a link field in "V4 DB Record Instance Syntax"


* <tt>choiceName</tt> A string that selects the link or device support.
== timeStamp ==
* <tt>dataStruct</tt> Each support has an associated struct for configuration.
 
How should these be made available? Perhaps:
 
The field appears as a string with the following syntax:
 
<tt>choiceName(structAssignmentList)</tt>
 
where structAssignmentList has the same syntax as defined in "V4 DB Record Instance Syntax"
 
=== timeStamp ===


This is just transfered like a struct with two fields:
This is just transfered like a struct with two fields:
Line 615: Line 551:




=== struct ===
== struct ==
 
The database definition syntax allows a struct to be composed of fields
of any DbfType.
Database access, however, will only allow access to structs with fields
of the following types:
* primitive - DbfBool,...,DbfFloat64
* DbfString
* DbfArray of primitive type or string
* DbfStruct - As long as its fields are valid types


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


Access will only be available to clients that have knowledge of
The entire structure can be accessed as a string with the same syntax
fields within the structure. For channel access clients this means that
as defined for a struct field in "V4 DB Record Instance Syntax"
they provide a propertyCatalog that has some subset of the fields in the structure.




=== array ===
== array ==


Arrays of the following types are accessable:
Arrays of the following types are accessable:
Line 654: Line 580:
directly if it satisfies the criteria for accessing a DbfStruct.
directly if it satisfies the criteria for accessing a DbfStruct.


Question: Should database Access be implemented so that record/link/device support can transfer an array in segments. Examples:
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 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 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.
Line 666: Line 592:




=== MDArray ===
== MDArray ==


Not implemented if the early V4 releases.
Not implemented if the early V4 releases.


=== Associated Data ===
== Associated Data ==


The typical example is a client that asks for timeStamp, severity, status,
The typical example is a client that asks for timeStamp, severity, status,
and data.
and data.
These are handled automatically as described in "Posting Modifications"

Latest revision as of 19:52, 2 November 2005

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.