EPICS General Time Related Information

Excerpts from EPICS Base release notes and EPICS Application Developer's Guide on general time (up to 3.14.12.2).

Release Notes R3.14.12.2
EPICS Application Developer's Guide [html] by Marty Kraimer et al. [pdf]

Changes on general time between 3.14.10 and 3.14.11

generalTime and epicsTime updates

Allow time providers to supply timestamps in interrupt context. A pair of new API routines in epicsTime.h epicsTimeGetCurrentInt() and epicsTimeGetEventInt() will check the most recently successful current-time or event-time provider and forward requests to the routine registered by that provider, if any. The priority list is not traversed, so if the latest provider has not registered an interrupt-safe routine by calling generalTimeAddIntCurrentProvider() or generalTimeAddIntEventProvider() as appropriate, these API routines will return failure. The resulting timestamp is not protected against backwards movement either.

Added a routine generalTimeHighestCurrentName() which returns the name of the highest prority registered current time provider. Comparing this with the name returned by generalTimeCurrentProviderName() permits an alarm to be generated if an IOC is not able to use the time provider it was designed to use. The General Time stringin device support keyword @TOPTCP has been added to make this name available in a database record.

The following routines have been renamed, but the old name may still be used since a macro with the old name has been added:

Old Name New Name
generalTimeCurrentTpRegister generalTimeRegisterCurrentProvider
generalTimeEventTpRegister generalTimeRegisterEventProvider
generalTimeCurrentTpName generalTimeCurrentProviderName
generalTimeEventTpName generalTimeEventProviderName

The routine generalTimeCreateSyncTimer() was not useful in practice due to time provider initialization issues, nor was its implementation protected properly for use on SMP systems so it has been deleted. The deprecated and empty synchronize() method from the epicsTime class has also gone.

Changes on general time between 3.14.9 and 3.14.10

General Time subsystem

The way in which EPICS gets the time has been significantly revised since R3.14.9 with the introduction of the General Time subsystem. Two kinds of pluggable time providers are now supported, which return either the current time or the latest timestamp of a numbered Time Event from a hardware event system. All IOCs must have at least one Current Time provider, but Event Time providers are optional. The General Time subsystem guarantees that the timestamps returned never step backwards, even when switching between time providers.

A Current Time Provider reports the current wall-clock time if it is able to when asked; if it can't it says so, and the time subsystem will then ask the next provider in its list and so on until someone replies with the time. Event Time providers are handled similarly, except that they are asked for the timestamp associated with a particular Time Event number rather than the current wall-clock time. The registered time providers can be listed using the IOC command generalTimeReport(int interest) and some time providers also have their own separate report commands.

Different target architectures come with different default Current Time providers in Base. The Unix-like architectures rely on the underlying operating system clock, which normally involves running something like ntpd as a separate process. The real-time operating systems vxWorks and RTEMS install two Current Time providers; the native operating system clock at the lowest priority (this provider includes a task to periodically reset the operating system clock from a higher priority time provider), and an NTP time provider which synchronizes the underlying operating sytem tick timer with an NTP server. Microsoft Windows targets using the Win32 API use a Windows-specific time provider which contains a built-in PLL.

There are no Event Time providers included with Base except for an optional "Last Resort" Event provider which can be installed if a site wants to be sure that every Time Event number will have a recent timestamp associated with it even if the hardware event system goes down. The Last Resort Event Time provider returns the current time for every Time Event number. To install this provider, run the command installLastResortEventProvider from your IOC startup script.

Additional information about General Time and the time providers included with Base can be found in the IOC Application Developers Guide for R3.14.10, sections 9.7 and 20.6. General Time was originally written by David H. Thompson and Sheng Peng at ORNL, subsequently worked on by Babak Kalantari and Timo Korhonen of PSI, and merged into Base by Peter Denison from Diamond. Andrew Johnson provided input into the design at various points and made various code revisions after the merge.

epicsTimeEventDeviceTime support for soft channel input records

The Soft Channel device support for all input record types now supports the fetching of the timestamp along with the data when the record's TSE field is set to epicsTimeEventDeviceTime (-2). This works for both DB and CA links. However the timestamp will only be fetched if the record's TSEL link is not set, so you can't point TSEL to another record to read the -2 value into TSE (that's because to make this work properly would require that the TSEL link be read twice every time the record processes; once in the soft channel device support, and again when the record type calls recGblGetTimeStamp().

Changes on drvTS between 3.14.7 and 3.14.8

drvTS and apsEvent support

The following files have been removed from base: drvTS.h drvTS.c, egDefs.h egRecord.c egRecord.dbd egeventRecord.c egeventRecord.c egeventRecord.dbd erDefs.h erDefs.h erRecord.c erRecord.dbd ereventDefs.h ereventRecord.c ereventRecord.dbd

These are removed from EPICS base. The version that previously came with base was the version that worked with the APS event system. It is available from APS. The version that works with the newer event systems that evolved from the APS system is available from the Swiss Light Source.

Changes on timestamp between 3.14.4 and 3.14.5

Stringin record time-stamp soft device support

Add simple device support for converting time to nicely-formatted string using INP field as epicsTimeToStrftime format string:
record(stringin, "$(user)now")
{
    field(DESC, "Current time and date")
    field(DTYP, "Soft Timestamp")
    field(INP, "@%Y-%m-%d %H:%M:%S.%03f")
}

Changes on timestamp between 3.14.0beta1 and beta2

timeStamp changes

Changes have been made to:

epicsTime.h now has the definitions:

#define epicsTimeEventBestTime -1
#define epicsTimeEventDeviceTime -2

These are values for the TSE field of dbCommon.

If the TSEL field refers to the TIME field of a record then recGblGetTimeStamp sets TIME equal to the time it gets from the record the TSEL references. This works for both database and channel access links. In this case field TSE is not used.

 

EPICS Application Developer's Guide (3.14.12.2)

9.8 General Time

20.6 epicsGeneralTime

20.15 epicsTime


[Please Comment on This Page]
<kazuro.furukawa@kek.jp>, Linac, KEK, Oct.22.2012 - Oct.22.2012.
[Event System] [Timing Another] [Control] [Linac] [Accelerator] [KEK]