ICS – Software Engineering Group 1 The SNS General Time Timestamp Driver Sheng Peng & David Thompson

ICS – Software Engineering Group 2 Why create a new timestamp driver? l SNS has a timing system that supports hardware timestamps and we use those timestamps to correlate data. l Existing timestamp support (in drvTS) calls the same time source for event timestamps (in record processing) as well as for scan task and I/O task scheduling. l No time source is 100% reliable, we wanted to provide for selection and use of an alternate source if the primary source is unavailable. l The built in EPICS time interface in iocClock.c does not provide for redundancy if a primary time source fails.

ICS – Software Engineering Group 3 The problem l At SNS we noticed on at least two occasions that some of our IOCS were not scanning records and that some vxWorks tasks had unusual delays in the task display. This required some expensive reboots. l The second time that we saw it happen we were ready and captured enough data to track the problem down to the GPS receiver in the timing system. l GPS keeps time in 1024 week “epochs”, our receiver jumped to an epoch far into the future and stayed there for a couple of minutes. When it jumped back many of our IOCs had drvEtherIp tasks in progress processing data and these got caught by turning a large negative time jump into a large delay. (The receiver was RMA-d for a firmware update and has behaved since.) l During normal timing system operation noise can be experienced on the RTDL causing transient problems.

ICS – Software Engineering Group 4 The problem l Even NTP is not perfect: We had one workstation that had a bad clock. It ran at about half time and made 15 second jumps to catch up. This caused it to mis-report “beacon anomalies” l Time itself is not monotonic! (UTC time at least) The mean solar day was “exactly” SI seconds in 1820, but in recent years it has been as much as seconds. A leap second is added every few years to adjust UTC. Since the earth is running slower than UTC then UTC must be set backwards by a second. The difference is about ½ second now. (

ICS – Software Engineering Group 5 What is generalTime? l It is a time source manager l It always selects the “best available” time source, depending on whether an event time or the current time is requested. l It supports hardware time sources i.e. timing system. l It provides two default time source: NTP & Ticks via clock_gettime(). l Can be extended by just adding time drivers as normal epics drivers to the system. »We are planning a driver to support on-board clock chips for full stand alone IOC Best available is the one that has the highest priority and is not returning ERROR. The driver must be able to know it is wrong.

ICS – Software Engineering Group 6 API (extending iocClockRegister) l General time calls: iocClockRegister(). l A time driver calls: generalTimeTpRegister(). Arguments: »Tcp_priority: Priority of current time function. »getCurrent: Pointer to current time function in your driver. »syncTime: A pointer to a function that general time calls to synchronize the time in the driver if needed. »Tep_priority: Priority of event time function. »getEvent: The event time function in your driver.

ICS – Software Engineering Group 7 API (Continued) l When an EPICS API function requests a current time or an event time, general time calls registered time functions in order of priority. l When a time driver returns OK the search for the time is stopped and that time is returned to the Epics system caller. l If the time function returns ERROR then the next lower priority driver is called. l The lowest priority time is the system time which should always be available, even if it is wrong.

ICS – Software Engineering Group 8 Details IocClock Functions drvGeneralTime/ devGeneralTime drvTimeVxWorks devTimeVxWorks drvUtil drvTimeNTP devTimeNTP drvTimeCMOS devTimeCMOS drvGeneralTime returns the highest priority time source available This is completely transparent to epics time and record processing functions. The devTimeXXX drivers must support an ai record returning seconds since 1/1/1990. The ai record can be linked to a string record for readable time or monitored with a calc record for differences.

ICS – Software Engineering Group 9 General time features: l General time is an Epics driver with device support. l The drvGeneralTime report function reports status and a list of time providers. l Device support provides string and ai record support for status of current time providers for both event time and current time lists.

ICS – Software Engineering Group 10 Utility module (SNS Hardware) l No longer uses drvTS. l USES generalTime interfaces. l The Utility driver has been improved because it no longer has to provide time when the RTDL is bad. The old driver had to implement NTP to provide back up time. l Returns error if time is bad, so general time can pick next best. »Timing master reboot causes zero timestamp errors in generalTime »The timing master will set a flag on the RTDL when it does not know the time for some reason. This will be passed up to general time. l The driver has had internal changes to detect and track VME and timing system errors.

ICS – Software Engineering Group 11 Conclusions l We would like to see general time replace iocClock in builds for real time OS. l General time is written using OSI calls. l Works the same as iocClock when hardware time is not available, even if hardware time is configured and installed. l drvTimeNtp is derived from iocClock.c l Probably most useful on vxWorks where the basic system time calls do not use NTP.