User Interface to the ACP Timer Interface
Brian J. Kramper
Fri Mar 29 09:05:16 CST 1996
There is the need to synchronize the various tasks in the Auxiliary Crate Processor (ACP) environment with the accelerator cycle. There is also the need to provide time-delayed events of both a single occurrence and of a repetitive nature for these tasks. This document describes a timer interface for these tasks. The intent is to offer a basic service to meet these needs.
The EPICURE data acquisition system has already defined a structure for specifying either a time within the accelerator cycle or a periodic rate for data sampling. The Frequency/Time Descriptor (FTD) is a 32-bit longword which has been divided into three fields: m, event, and interval. The m field indicates whether the data is to be acquired at a periodic rate (FTD_C_FREQ), at a time synchronized with the phase reversal clock (FTD_C_PHICLK), or at a time synchronized with the Tevatron clock (FTD_C_TEVCLK). The event field indicates which clock event is to be used: 1 through 15 for the phase reversal clock, and 0 through 253 for the Tevatron clock. (For the Tevatron clock event 254 is used to trigger an immediate event, FTD_C_NOWEVT.) The event field has no meaning for a periodic event not synchronized to one of these two clocks. The interval indicates the rate in milliseconds for periodic events, or the delay in milliseconds after a specified clock event. Since this structure has already been specified and satisfies the requirements for these timer services as well, the FTD will be used as the basic timing descriptor for the ACP timer services.
The ACP will be using VRTX32 from Ready Systems, Palo Alto, CA, as its system kernel. VRTX32 provides four methods of intertask communication: mailboxes, queues, event flags, and semaphores. The ACP timer interface will provide the ability to use any or all of these four methods of communication between the timer task and the user tasks.
The timer service routines are functions which return a standard VRTX32 status code of the form OK or ER_xxx. If the status must be reported outside the environment of the ACP, it will be the responsibility of the user task to translate the VRTX32-type status code into an error code commensurate with the target environment.
The timer task has the responsibility for maintaining ordered lists of requests for time-oriented events using both the accelerator clock and line frequency intervals. Requests are passed to the timer with the set_timer call. Upon receipt of a timer request, response identifiers are verified for event flag groups, queues and semaphores since this can be done using the appropriate inquiry calls to VRTX32. When the indicated event occurs, the requesting task is notified of the event via one of the four communication methods.
Status returns within the scope of the ACP itself will return VRTX error codes. If these errors need to be transmitted outside the scope of the ACP, e.g., to a task on a front end CPU, the error codes must be translated into VMS-type status codes.
set_timer status = set_timer( ftd, handle, mode, resp_type, resp_id, msg_mask ) Request by a task to be notified when a specific timing event has occurred. ftd Longword value of a standard format FTD to indicate whether the operation is based on the accelerator clock or line clock. Passed by value. handle Longword identifier returned to the calling task. This is used to identify the request for a matching cancel. Passed by reference. mode Longword value indicating whether this is a REPEAT operation to be rescheduled upon completion, or a ONE_SHOT and not rescheduled. Passed by value. resp_type Longword value indicating whether the response is to be passed via event flag, mailbox, queue, or semaphore. Passed by value. resp_id Pointer dependent on the resp_type. If the resp_type is an event flag, then this is the pointer to the event flag group identifier returned by a previous sc_fcreate. If the resp_type is a mailbox, then this is a pointer to the mailbox allocated by the calling task. If the resp_type is a queue, then this is a pointer to the queue id number used in a previous sc_qcreate or sc_qecreate. If the resp_type is a semaphore, then this is a pointer to the semaphore id number returned by a previous sc_screate. msg_mask Pointer dependent on the resp_type. If the resp_type is an event flag, then this is a pointer to the longword mask indicating the event flag(s) to be set via sc_fpost at the expiration of the request. If the resp_type is a mailbox, then this is a non-zero pointer-sized message to be posted via sc_post at the expiration of the request. If the resp_type is a queue, then this is a pointer-sized message to be posted via sc_qpost at the expiration of the request. (Zero is allowable as a message value here.) If the resp_type is a semaphore, this argument is ignored and the semaphore is just incremented via sc_spost. status OK success ER_ID event flag group or semaphore id error ER_ZMW zero message ER_QID queue ID error; no such queue
cancel_timer status = cancel_timer( handle ) Cancel a previous timing event request. req_id Longword identifier previously returned to the calling task. Passed by value. status
OK success ER_NXR non-existent request