RD Controls Software Release Note 40.0<P> <b> User Interface to the EPICURE Timer Interface</b>

RD Controls Software Release Note 40.0

User Interface to the EPICURE Timer Interface

R. West, D. Baddorf, T. Lahey,

M. Moy, F. Nagy, A. Thomas

August 5, 1988


The need to synchronize various computer programs to the accelerator cycle is obvious. Some functions may require that a program respond in less than a millisecond. These situations are frequently accorded a dedicated processor or, optimistically (in the case of multi-programmed systems), high priority for attention by the operating system. Other functions are less time-critical and can tolerate a resolution of ten or perhaps even one hundred milliseconds. Such ``slower'' response functions usually involve interfaces with human beings who don't notice much difference between a delay of one millisecond and, say, 30 milliseconds.

The high resolution timing desirable for the EPICURE data acquisition subsystems makes use of multiple dedicated processors (data acquisiton engines) to perform timing and data communications. Other processors on the network rely upon these data acquisition engines for all time-critical processing. In particular, the Data Acquisition Requestor (DAR) process on each participating network node has an interest in the accelerator clock in order to ``time-out'' a request. It is highly desirable that the method of determining this ``time-out'' be independent of the data acquisition protocol (and hardware) itself. Also, an independent means of verifying clock operation at the application program level is a valuable diagnostic tool. In any case, this kind of timing service is of potential use to other ``system server processes.''

This document describes a timer interface for programs anywhere in the network. The intent is to offer a basic service which does not require custom hardware for an initial implementation but which may be augmented by such hardware on network nodes where the service is popular. This is achieved by using network communications between requesters of the timing service and one (or several) server nodes which possess clock interface hardware. In the initial implementation, the server nodes are EPICURE front-end processors, each with an attached data acquisition engine and timer processing element. While this certainly does not satisfy the goal of a wholly independent source for verifying the operation of the data acquisiton engines themselves, it does allow the rest of the timer services subsystem to be defined, implemented and tested without the need for any additional custom hardware implementations.

In the future, the timer server running on each node will check to determine the presence of a hardware clock interface. If such an interface exits on the node, it will be used in preference to a server on some other node in the network. If not, then requests will be forwarded to a timer server on a network node which is known to have access to a hardware interface. As long as reasonable care is taken in the selection of allowed clock events for which notification may be requested, there should not be an adverse impact on network loading - as long as the number of nodes remains relatively small. As the network grows, it will be necessary to equip all high traffic nodes with clock interfaces in order to avoid wasting valuable network and CPU resources.

Frequency-Time Descriptor (FTD)

The data acquisition system allows the specification of a sample time within the accelerator cycle or an asynchronous periodic rate for each data request. The Frequency-Time Descriptor (FTD) defines a uniform method of specifying such a time or rate. An FTD is defined to be a single 32-bit longword divided into three fields: m, event, and interval. The m field specifies the type of sample time: periodic rate (FTD_C_FREQ), phase reversal clock (FTD_C_PHICLK), or Tevatron clock (FTD_C_TEVCLK). The event field specifies the number of the clock event: 1 through 15 for the phase reversal clock and 0 through 253 for the Tevatron clock. The interval field specifies the rate interval in milliseconds for a periodic event or a delay in milliseconds after a clock event. The C language structure declaration FTD and the symbols for the m field are included in the VAX file EPICURE_INC:FTD.H.

Timer Service Routines

The system timer service routines are all functions and return a standard status code as the function result as described in EPICURE Design Note 5 ``System-Wide Status Codes And Error Reporting.'' The routines follow the argument-passing standards as described in EPICURE Design Note 18 ``Conventions For Writing And Documenting EPICURE System Procedures.''

Asynchronous Timer Request

status = TS_SET_TIMER_NOWAIT(ftd, request_id, [mode], [efn], [ast_routine]);

Set a timer to expire at the specified ftd. When the ftd occurs, the event flag is set and/or the AST routine is entered. Either the event flag or the AST routine must be specified. If neither is specified, the request is rejected and an error status is returned.

the address of a standard format FTD which specifies a time in the accelerator cycle or an asynchronous periodic rate.

a longword value identifying the timer request. The invoking application should retain this value since it is required to cancel an individual timer request. It is not necessary that the request_id's given by the user be unique for successive calls to this service routine. However, it is the responsibility of the user to handle the case in which the same request_id is used multiple times.

a longword set to the symbolic value REPEAT or ONE_SHOT specifying whether the timer request is to be rescheduled once it has been satisfied. The default value of this argument is REPEAT.

a longword value containing the number of an event flag to be set each time the ftd is satisfied. It is strongly recommended that the caller use the VAX/VMS run time library routine lib$get_ef to allocate a local event flag. When used in the REPEAT mode, it is the responsibility of the caller to clear the event flag each time notification takes place. Failure to do so will result in the flag being set at all times. This service clears the event flag only at the initial invocation.

the address of an AST routine to be entered when the timer request has been satisfied. The AST service routine is called with the following arguments:

Synchronous Timer Request

status = TS_SET_TIMER_WAIT(ftd);

Set a timer to expire at the specified ftd. Control is not returned to the caller until the specified ftd is satisfied. The timer request is a one shot. It is not rescheduled.

the address of a standard format FTD which specifies a time in the accelerator cycle or an asynchronous periodic rate.

Cancel a Timer Request

status = TS_CANCEL_TIMER(request_id);

Cancel any outstanding asynchronous timer request having the specified request_id. If the same request_id has been given to multiple requests, all requests with this id are cancelled.

the request_id argument specified when the timer request was

initiated via TS_SET_TIMER_NOWAIT

Cancel All Timer Requests


Cancel all outstanding timer requests which have been made by the caller's application.

Status Returns

The status values returned by the timer service routines are:

Security, Privacy, Legal