LCLS Controls

SLC-Aware IOC Functional Requirements

This is a DRAFT!!! Work is in-progress!!!
Quick links:

A. Introduction

This section is taken verbatim from LCLS Specification #1.2-201 written by the LCLS Controls Group on May 2004. Additional background is found in Distributed Control System Requirements by Patrick Krejcik, Nov 2003.

A.1 Background

The SLC control system at SLAC is currently used on most of the LINAC. It is the only control system in sectors 20-30, which will be used by the LCLS mostly intact. LCLS will replace all of the BPM electronics in these sectors to provide higher resolution. The Injector for LCLS will use all new control, except for the high power RF components, which are existing SLC klystrons and modulators. The corrector magnets in the LINAC that will be used for LCLS will all have new EPICS based controllers. From the undulator to the experimental stations, all new controls will be done in EPICS. Note that all SLC data from the existing LINAC will be available to the EPICS environment, but the time stamp information that allows data correlation to beam events is not available at the present.

The motivation to implement an SLC aware, EPICS IOC, is to allow the new elements of the LCLS control system to use EPICS, while still taking advantage of the high level applications on the SLC control systems. These high level applications include:
Correlation plots, energy management, beam steering, beam based alignment, emittance measurements, and slow feedback.

The SLC aware IOC requires that we have:

  1. Simple polled data transfers
  2. Timed acquisition for beam synchronous data
  3. Buffered acquisition of beam synchronous data
  4. Perhaps some other communication methods

A.2 Risk and Risk Mitigation

If we are unable to develop the required communication emulation, we will not be able to run the high level applications on the SLC Host. Not having access to high level applications may have a negative impact on the commissioning schedule.

There are several ways that we are managing this risk:

  1. We have already started identifying the types of SLC micro communication messages that are required. We will write the emulators incrementally as they will be required.
  2. All SLC micro data, the critical BPMs, low level RF, and correctors will be in native EPICS environments. This allows us to use write new high level applications in the EPICS native environment even if we do not have time correlated data from the SLC micros. We can also adopt existing physics applications and tools from other laboratories.
  3. We have allocated 3 FTEs per year to manage both the integration of the SLC aware IOC and the EPICS native high level applications.

A.3 Treaty Points with SLAC Timing System

  1. Make SLC time stamped data available to EPICS
  2. Make EPICS data available to SLC periodic update task
  3. Make EPICS time stamped data available to SLC host
  4. Make EPICS buffered, time stamped data available to SLC host
End of section taken verbatim from LCLS Specification #1.2-201.

B. System Description and External Interfaces

An IOC (Input/Output Controller) consists of a set of tasks on a single board computer (SBC) or a single process with a set of threads on a Unix workstation. In this document, "task" means either a SBC task or a process thread. A "normal" IOC, like those in the PEPII project, has just EPICS and CMLOG tasks. An "SLC-aware" IOC (aka "SLC IOC" or "IOC micro") adds groups of tasks to the normal IOC to interface with the SLC control system. Figure B-1 is a block diagram showing the SLC task groups (aka "jobs" or "services") (within the dashed line) and the interfaces with external tasks and resources.


Figure B-1: System Block Diagram and External Interfaces

B.1 SLC IOC Description

A brief description of each SLC task group is provided here. Specific requirements are listed in later sections:
  1. SLC Executive
    The SLC executive is started after both CMLOG initialization and EPICS iocInit during IOC startup. It exists through the lifetime of the IOC and is responsible for starting and stopping all other SLC tasks in the proper order.
  2. SLC Message Service (MSG)
    The IOC SLC message service accepts a subset of Alpha SLC request messages that are structurally the same as those sent to SLC micros. These messages are queued for other tasks to process. If necessary, the other tasks then queue replies to the requests, each normally consisting of status and data (if applicable), which the SLC message service sends back to the requesting Alpha process. In general, messages are expected to arrive at 1 Hz or less with a possiblity of 10 Hz during short periods of high activity. The SLC message service also processes TEST messages, specifically the existence test message from the Alpha PARANOIA process.
  3. SLC Database Service (DBS)
    On startup, the SLC database service downloads the IOC's part of the SLC database from the Alpha Database Executor (DBEX) process and creates it locally on the IOC exactly like the SLC micro. This service then accepts new setpoints (supertype 2 data) from DBEX and updates the local SLC database, sending acknowledgements to DBEX when required. Updates from DBEX are expected to arrive at much much less than 1 Hz with a possiblity of up to 10 Hz during short periods of high activity.

    Other SLC tasks update readbacks (supertype 3 data) in the local SLC database and queue update requests about once every 5 to 60 seconds. These SLC tasks also update setpoints changed by EPICS in the local SLC database and queue update requests at much much less than 1 Hz with a possiblity of up to 10 Hz during short periods of high activity. The SLC database service acts on these update requests by sending the data on to DBEX and waiting on acknowledgement.

  4. Cluster Status Update (CSTR)
    This task updates all CSTR health and status secondaries (supertype 3 data) by periodically reading associated EPICS PVs, updating the local SLC database, and queueing an update request to the SLC database service.
  5. Device Control and Readback (MGNT)
    Later
  6. Gated ADC Acquisition (BPM)
    Later
Currently, there are no plans to support SLC messages and SLC database entries for analog status, digital status, fast feedback, timing, and MPS module configuration. These subsystems will be pure EPICS.

B.2 SLC IOC External Interfaces

External interfaces include the following:

  1. Alpha SLC Message Service used by SCPs and standalones. Requests and replies are transferred using TCP/IP. Messages are transferred through a proxy task running on Linux which funnels and thus minimizes connections in both directions.
  2. Alpha DBEX process for downloading the database and keeping both sides in synch. TCP/IP messages are transferred through the proxy.
  3. NFS server which contains the PRIMARY.MAP file created during Alpha database generation (DBGEN) and copied to production by Alpha database installation (DBINSTALL). The SLC database service reads this file during startup for database definition. The NFS server is also used by IOC shell, when required, for diagnostic file output.
  4. CMLOG client consisting of a daemon and an EPICS errlog "listener" tasks which receive and process error and informational messages logged by both EPICS and SLC interface tasks.
  5. IOC shell (and possibly other EPICS tasks too, TBD) which access the SLC shared resources and database allowing console users to view diagnostics and perform a limited set of commands.
  6. EPICS resources and EPICS database accessed by the device control, gated ADC acquisition, and cluster status SLC tasks to update new setpoint values, activate EPICS commands as a result of SLC message requests, and periodically get readback values.

C. General Requirements

C.1 SLC and EPICS

  1. SLC tasks do NO hardware access, control sequences, or calculations. EPICS does this work.
  2. There is no requirement to transfer high-level application data (supertype 4), used by VMS applications and not currently downloaded to SLC micros, to and from the EPICS database.
  3. There is no requirement to keep static, rarely changed data (supertype 1) in synch between the EPICS and SLC databases. Supertype 1 data may be changed on-the-fly in the IOC SLC database by IOC shell. Users may want to manually change supertype 1 data after an Alpha DBEDIT to avoid IOC restart.
  4. Requirements for the creation of EPICS and SLC database files will be described elsewhere.
  5. All SLC tasks are lower in priority than the highest priority EPICS tasks. Some SLC tasks are higher in priority than the channel access server. TODO: A table with EPICS and SLC functions and their relative priorities is needed!!
  6. SLC IOCs can be used for all EPICS projects (not just LCLS).

C.2 Operating System

  1. SLC IOCs run on RTEMS, VxWorks, Linux, Solaris, and possibly Macs (for LCLS only).
  2. RTEMS or VxWorks SLC IOCs run on any supported microprocessor.
  3. The CMLOG client is currently available for VxWorks, Linux, and Solaris. It must be ported to RTEMS and Macs, if necessary.
  4. Multiple SLC IOCs can run on one Linux or Solaris machine. However, a message logged without the micro name tag (see Message Logging section below) on these IOCs is shown as coming from the host machine and not the specific IOC that logged the message.
  5. Messages and data from the VMS control system are little-endian and in VMS formats. SLC tasks convert to or from little-endian/VMS where necessary (words, floating point, and time).
  6. There is no requirement that the timestamp on the IOC be synchronized with the timestamp on the Alpha. Any timestamp set by the Alpha in a message or in the database is not used in any calculation (ie, delta time) with an IOC timestamp.
  7. Conversion from a GMT EPICS timestamp to a local VMS timestamp is required. Timestamp conversion from VMS to EPICS is not required.
  8. Unlike the Alpha, daylight savings time on the IOC is automatic. Any local VMS timestamp set by the IOC in a message or in the database is an hour different from the Alpha until the Alpha is manually adjusted later on Sunday. It is expected that functionality will not be impacted.

C.3 Proxy

  1. Any SLC task maintaining a connection with the proxy automatically reconnects to the proxy when the proxy is restarted. There is no need for SLC task restart ("IPL") unless the proxy is down long enough for the Alpha PARANOIA process to set the IOC "offline".
  2. Development SLC IOCs connect to the development proxy and production SLC IOCs connect to the production proxy.
  3. Currently, there is one proxy task to handle ALL production SLC micros and IOCs. If that proxy cannot handle both the PEPII and LCLS traffic or if there is a need to do a "realm-split" to provide independence of projects or machine regions, multiple proxies will be allowed. This will require changes to the existing Alpha message service.

C.4 Startup and Shutdown

  1. A failure of the SLC executive to start does not prevent EPICS and CMLOG from running normally.
  2. Environment variables are used to determine if an SLC IOC runs on development or production system. There is no requirement that the production or development mode be changeable on-the-fly.
  3. Environment variables are set during IOC startup to define:
    • Micro name
    • Location of the PRIMARY.MAP file
    • Proxy host
    • CMLOG server host and port
  4. It is a design goal but not a requirement that the SLC executive be able to stop and restart the SLC tasks on user request without requiring an entire IOC restart or halt. Starting and stopping are achieved by IPL and reset from the SCP, IOC shell request, and, optionally, channel access. There is no requirement to restart the SLC tasks when requested by the broadcast from the PNET module which is generated by the MPG.
  5. Before stopping SLC tasks, the SLC executive waits for any SLC-related IOC shell command to complete. Before starting SLC tasks, the SLC executive waits for any existing SLC task to exit. A failure of any command to complete or task to exit in a timely manner is considered a fatal error and an IOC restart is required to recover.
  6. All SLC tasks are able to receive a message from SLC executive to perform a normal exit. Right before exiting, all tasks reply to SLC executive that they have stopped.
  7. While SLC is stopped, all SLC-related IOC shell commands, except restart, output an error message to the console and do nothing more.

C.4 Resource Management

  1. Resources allocated by SLC tasks are used only by SLC tasks with the exception of the EPICS IOC shell (TBD, maybe other EPICS tasks too). Shared resources are properly protected.
  2. On shutdown, each SLC task frees any EPICS or SLC resource it has taken and deallocates any resource it allocated.
  3. If SLC restarts are implemented without requiring an IOC reboot, then to prevent memory fragmentation on single board computers, memory management using memory pools is required.
  4. Any failure to allocate a resource results in a fatal error message and task exit or suspension. An IOC restart is required to recover.

C.5 Message Logging

  1. Except for the SLC executive and IOC shell which have no message logging requirements, all SLC tasks use CMLOG for message reporting and initialize as CMLOG clients on startup and free themselves from CMLOG on shutdown.
  2. All messages that are logged directly by SLC tasks have the following tags:
    • formatted message text
    • formatted condition code string
    • integer condition code with optional log-only bit
    • condition severity string
    • micro name
    • task name
    • destination SCP ID ("V017" means message is not associated with a specific SCP)
    Optional tags include the file name and line number where the error occurred. Detail requirements and design of SLC CMLOG utilities are documented in the Specification for Condition-Code-Specific CMLOG Routines.
  3. All messages that are logged directly by SLC tasks as a result of a request from a SCP are displayed on that SCP only. Any task handling an SLC message copies the source SCP ID from the SLC message header to the destination SCP ID used by logging and restores it back to "V017" after SLC message processing is complete.
  4. All messages that are logged by EPICS utilties called by SLC tasks have only these tags:
    • formatted message text
    • node name
  5. Predefined "noisy" message are throttled using SLAC-style throttling.
  6. An existing SLC message code is used whenever the message is conceptually the same as the one used by the SLC micro or if it is expected in a reply message back to the Alpha. The text of the message may be altered to use IOC/OSI instead of micro/RMX language.
  7. When no existing SLC message code is obviously available, new message codes are added to the existing VMS message definition files. The number of new codes is minimized.
  8. Development SLC IOCs send messages only to the development cmlogServer and production SLC IOCs send messages only to the production cmlogServer.

C.6 Diagnostics

  1. Each task keeps diagnostics and allows access to the diagnostics from the IOC shell.
  2. It is a design goal but not a requirement that a subset of the diagnostics are made available to channel access via EPICS records.
  3. EPICS EDM displays allow display and control of IOC health including:
    • IOC Reboot
    • SLC Restart
    • SLC Stop
    • Diagnostic data reset for some tasks (design goal)
    • Subset of diagnostic data display per task (design goal)
    • EPICS IOC diagnostics including CPU, file descriptor, and memory usage

C.7 Software Development

  1. SLC IOCs mimic the SLC micros (in action and timing) to minimize changes in the VMS control system software.
  2. SLC IOC source is maintained like an EPICS package and use EPICS-style Makefiles.
  3. An EPICS IOC application that needs the SLC interface includes the SLC libraries in its Makefile and adds the SLC environment variables and startup command to its startup file.
  4. To make it easier to port the existing SLC micro code where necessary, all source is C instead of C++.
  5. SLC tasks use EPICS operating-system-independent (OSI) functions to minimize platform-dependent source.
  6. In addition to OSI functions, SLC tasks may use well-designed EPICS utilities. Any utility that allocates resource must provide for resource deallocation. Recommendations for coders are kept in the Review of Epics Libraries and Resource Usage document.
  7. To access the EPICS database, SLC tasks use runtime database access instead of channel access for efficiency.
  8. SLC source is kept in AFS. The master copy is kept in the EPICS CVS repository.
  9. The number of include files that are FTPed from VMS to AFS is minimized and include message code definitions, message service structures, and database structures.
  10. When both EPICS and SLC provide similar typedefs, defines, or macros, the EPICS ones are used.

C.8 LCLS-Specific Requirements

  1. Full integration testing of the SLC IOCs on VxWorks can be done later since this platform is not required by LCLS.
  2. Full integration testing of the SLC IOCs on VxWorks or RTEMS non-PPC platforms can be done later since LCLS uses only PPCs.
  3. LCLS will import the master copy of SLC code into the LCLS CVS repository and keep it up-to-date when allowed by the maintenance schedule.
  4. The LCLS NFS server will probably be different from the MCC NFS server. Some mechanism will be needed to copy the PRIMARY.MAP file from the MCC NFS server to the LCLS NFS server when it changes.
  5. It is possible that for LCLS production, a separate LCLS-dedicated cmlogServer and cmlog browser that forwards messages to the Alpha (fwdBro) are required (TBD). These processes will probably run on Linux instead of Solaris. This will require changes to the existing production CMLOG setup and possibly some changes to the Alpha and fwdBro.

D. SLC Message Service (MSG)

D.1 Accept and Queue Messages

  1. Accept all SLC message service requests coming from the Alpha via the proxy.
  2. Incoming messages are no larger than 64K.
  3. Convert message header from VMS to native format. The message data is left in VMS format to be converted by the task that processes the request.
  4. Copy the source SCP ID from the message header to the destination SCP ID used by message logging. Reset after the message is queued.
  5. Override the timestamp in the message header that was set by the Alpha with the current local VMS time to be used by the task that processes the request for diagnostic purposes.
  6. Queue each SLC message in the appropriate job queue based on service code (TEST, MGNT, BPM) which is a part of the function code. Drop any message with an unsupported service code. Queue each message as it arrives (first come, first queued).
  7. Accepting and queueing messages is a lower priority function, compared to handling and replying to messages already in the queue.
  8. Log the following conditions:
    • Message service successful startup
    • Message service shutdown
    • Proxy connection down
    • Proxy connection back up
    • Invalid message header
    • Invalid service code
    • Unable to queue a message
    • Queue full
  9. Update the following diagnostics, reset some on-demand:
    • Total number of startups
    • Total number of shutdowns
    • Total number of messages received
    • Total number of messages dropped due to error
    • Maximum and average message size
    • Time of last request
    • Total number of times the proxy connection is established
    • Current proxy connection status
    • Time of last request for each service (TBD)
    • Maximum and average message size per service (TBD)

D.2 Send Reply Messages

  1. Read a reply from a queue (first-come, first-served) and send it to the Alpha via the proxy. This queue is filled by other SLC tasks that formulate a reply after processing a request.
  2. Reply messages are no larger than 64K.
  3. If the connection to the proxy is down, the replies wait in the queue for the connection to be reestablished.
  4. Copy the destination SCP ID from the reply message header to the destination SCP ID used by message logging. Reset after reply is sent.
  5. Set the current local VMS timestamp in the message header.
  6. Set reply bit in the function code in the message header.
  7. Convert message header from native format to VMS format first.
  8. Replying to messages is a higher priority function, compared to handling and accepting new messages.
  9. Log the following conditions:
    • Proxy connection down
    • Proxy connection back up
    • Invalid message header
    • Unable to send a message
  10. Update the following diagnostics, reset some on-demand:
    • Total number of reply messages sent
    • Total number of reply messages that could not be sent
    • Maximum and average reply message size
    • Total number of times the proxy connection is established
    • Current proxy connection status
    • Maximum and average delta time between the time of the request and the time of the reply
    • Time of last reply

D.3 Process Messages with TEST Function Codes

  1. Take a message with the TEST function code out of the TEST job queue, first come, first served.
  2. Copy the source SCP ID from the message header to the destination SCP ID used by message logging. Reset after reply is queued.
  3. Handle the following function codes:
    Function Code
    Action
    TEST_EXISTENCE Existence check from PARANOIA. Reply with data exactly as sent.
    TEST_ECHO Reply with data exactly as sent.
    TEST_ECHO_MWORD Reply with blocks of repetitions for given word.
    TEST_ERR_METER_RESET Reset cmlog throttling (TBD). Reply with the throttling reset status.
    TEST_IOC_SLCNOTIFY Reply with status first. Send message to SLC executive to either restart or stop all SLC tasks depending on the message data.
  4. Copy the source and destination from the request message header to destination and source, respectively, in the reply message header. Copy the VMS timestamp and function code from the request to the reply message header. Set the proper data length in the reply message header.
  5. Queue reply in the message reply queue.
  6. Log the following conditions:
    • Invalid function code
    • Unable to queue a reply
    • Queue full
  7. Update the following diagnostics, reset on-demand:
    • Total number of messages processed for each function code
    • Total number of message replies
    • Total number of replies dropped due to error
    • Time of last existence check
    • Maximum and average delta time between the time of receipt and the time of reply for existence checks

D.4 Message Utilities

Functions used by more than one task include:
  1. Take an SLC message out of a queue.
  2. Set up a reply message header.
  3. Put a reply message into the reply queue.
  4. Conversion for each primitive data type to convert to and from VMS and native formats.
  5. Convert GMT EPICS time to VMS local time.
  6. Get current GMT EPICS time and convert to VMS local time.
  7. Find difference between two local VMS timestamps.
  8. Proxy connection handling and sending and receiving messages (shared with the SLC database service).

E. SLC Database Service (DBS)

E.1 Download and Create Database at Startup

  1. At startup, transfer messages with DBEX via the proxy to download the IOC's part of the SLC database from the Alpha to the IOC. The message structures are identical to those transferred between DBEX and the SLC micros. All downloaded "pieces" must arrive in a known sequence. The database is put into memory accessible by all tasks.
  2. Convert offsets into the database (supertype 0 data) from VMS to native format. Leave the rest of the database in VMS format.
  3. Read the PRIMARY.MAP ASCII file and create a character-based hash table to hold information about each primary and about each secondary of each primary. Information includes primary name and number, secondary name and number, data type, data width, and array size ("V" if variable).
  4. If the database and file are loaded without error, set a database-exists flag used by other tasks. Reset the flag if any error. Set event that the database download is complete to release tasks waiting on this event.
  5. Log the following conditions:
    • Any database download or timeout error
    • Problem with offset conversion
    • PRIMARY.MAP read or format error
    • Error creating and populating hash table
    • Database service successful startup
    • Database service shutdown

E.2 Accept and Process Database Changes and Up/Down Messages from DBEX

  1. Receive setpoint (supertype 2) database updates or up/down messages from DBEX via the proxy. The supertype 2 update message is structurally identical to that sent by DBEX to the SLC micros.
  2. If a data update message is received, update the local SLC database. Other tasks that need to do database access block while the update occurs.
  3. If an up/down message is received, set or reset a flag that indicates DBEX is available. If DBEX is now available, save the database major/minor ID from the message for diagnostics.
  4. If DBEX is now available, add a message per job to the SLC database send queue to send any outstanding data updates for that job to DBEX.
  5. Send message acknowledgement back to DBEX via the proxy if requested.
  6. Processing database changes is a higher priority function, compared to handling and accepting new messages.
  7. Log the following conditions:
    • DBEX state change.
    • Proxy connection down
    • Proxy connection back up
    • Invalid message from DBEX
    • Unable to send acknowledgement
  8. Update the following diagnostics, reset some on-demand:
    • Total number of data updates received
    • Total number of data updates dropped due to error
    • Time of last data update
    • Total number of times that DBEX was flagged as down
    • Current DBEX state
    • Database major/minor ID
    • Total number of times the proxy connection is established
    • Current proxy connection status

E.3 Send IOC-Generated Database Changes to DBEX

  1. The SLC database service reads a database update request from a queue (first-come, first-served). Note that when an SLC task updates the SLC database using dblput (see Database Utilities section below), a per-job update table which keeps track of what needs to be sent to DBEX is updated. The mechanism used to provide an efficient way to send updates to DBEX is exactly the same as that used on the SLC micro and involves "high/low water marks". After the task is done with all its updates, it adds an update request with job ID to the SLC database send queue.
  2. A message is created for the job based on the contents of the job update table and the local SLC database.
  3. The update message is sent to DBEX via the proxy and includes a request for acknowledgement using a unique code that DBEX must provide in its acknowledgement message. This code is incremented with every update message that is sent and rolls over at 256.
  4. Until the update message is either acknowledged or an acknowledge timeout occurs, no further updates are processed and newer update requests remain in the queue. No other task can update the database for the associated job after the message is created and before acknowledgement of the message is received. Database reads may be allowed (TBD). Double-buffering of the job update table relaxes this restriction (TBD).
  5. If the connection to the proxy is down, all database update requests are dropped (the queue does NOT fill up).
  6. When the connection to the proxy comes back, updates for all jobs is done automatically and immediately.
  7. Sending updates to DBEX is a higher priority function, compared to handling and accepting new messages and replying to old messages.
  8. Log the following conditions:
    • Proxy connection down
    • Proxy connection back up
    • Unable to send a message
  9. Update the following diagnostics, reset on-demand:
    • Total number of updates sent
    • Total number of updates dropped due to error
    • Time of last update (per job?)
    • Total number of times the proxy connection is established
    • Current proxy connection status

E.4 Wait for and Process Acknowledgements of Database Updates from DBEX

  1. A wait for a valid acknowledgement from DBEX via the proxy is done with a timeout of 15 seconds or less. If DBEX is flagged as down, a shorter timeout is used.
  2. Any invalid acknowledgement received during this time is dropped. The wait then continues with whatever time is left. To be valid, the code in the acknowledgement must match the expected code in the update message that was sent.
  3. If DBEX is flagged as down and ANY acknowledgement (valid or invalid) is received, flag DBEX as available.
  4. If the message is sent successfully and a valid acknowledgement received, the job update table is cleared. If there is any error, the job update table is not cleared and the next time an update request is done, data from the previously unsuccessful updates are included.
  5. Any task that needs to update the database and thus the job update table while the send and wait cycle is active for that job, blocks until the cycle finishes.
  6. Processing acknowledgements from DBEX is the highest priority function of all SLC tasks.
  7. Log the following conditions:
    • Proxy connection down
    • Proxy connection back up
    • Timeout waiting for acknowledgement
    • Invalid acknowledgement received
    • DBEX was flagged as down and is now available
  8. Update the following diagnostics, reset on-demand:
    • Total number of acknowledgements received
    • Total number of invalid acknowledgements received
    • Total number of timeouts
    • Time of last acknowledgement
    • Current DBEX state
    • Total number of times the proxy connection is established
    • Current proxy connection status
    • Maximum and average delta time between the time of the send and the time of the receipt of a valid acknowledgement

E.5 Database Utilities

  1. dblist: Update the input pointer list for input ASCII primary, unit, and secondary, allocating memory as needed. Unit may be "ALL*". If the database does not exist and is being created, first wait, with a fixed empirically-derived timeout, for the creation to finish.
  2. dblunits: Update the input data list with ASCII unit names for the input primary, allocating memory as needed. Same wait requirement as for dblist.
  3. dblget: If the database exists, get values from the database using the input pointer list, convert from VMS to native format, and update the input data list, allocating memory as needed. If another task is writing to the database, block until it is finished.
  4. dblput: If the database exists, convert the values in the input data list from native to VMS format and write them into the database using the input pointer list. If another task is reading or writing to the database, block until it is done. If the data is supertype 2 or 3, update the job update table that keeps track of what needs to be sent to DBEX. If a wait for a DBEX acknowledgement of a previous update for the job is in process, block supertype 2 and 3 updates until ready.
  5. micro_dbsend: If the database exists, add an update request to the SLC database service send queue for the input job (TBD) to update DBEX now.
  6. dballoc, dbfree: For allocating and freeing pointer and data lists.
  7. dbunit2string: Convert integer unit to ASCII name.
  8. dbexists: Check if the database is available.

E.6 IOC Shell Interface

  1. dbgettype: Returns the native data type for an input primary and secondary name.
  2. dbdump: Writes value(s) for the input primary, optional unit, and optional secondary to file or console.
  3. dbdumpunits: Writes units to file or console for an input primary name.
  4. dbedit: Update the local SLC database for input value(s) for an input primary, unit, and secondary. Can be used for supertype 1 data. Do we need to log these dbedits?
  5. dbdumphash: Dump hash table created from PRIMARY.MAP to file or console.
  6. dbdumpdatabase: Dump the whole SLC database to file or console.

F. Cluster Status Periodic Update and Async Utilities

G.1 Periodic Update

  1. At startup, both the time of the restart request (CSTR VTIM) and the SLC restart timestamp (CSTR MTIM) are set once to the current local VMS by calling dblist for each secondary, dblget, overwrite values, dblput, micro_dbsend, and dbfree for the pointer and data lists.
  2. At startup, CSTR AMSK and MSTA are also set - TBD.
  3. Setup is done for periodic processing by calling dblist for each CSTR secondary to be updated and dblget to allocate the data list. Secondaries include:
    CSTR Secn
    Description
    CRTS (TBD) Crate Status Mask
    CRTT (TBD) Crate Temperatures (degF?)
    CRV1 to CRV7 (TBD) Crate Voltages (V?)
    UTIM Last database update time per job
    CTIM Last async update time per job
    ELPS Elapsed time for last update per job (seconds)
    NRUN Number of executions in last calculation interval per job
    FAIL Number of failed executions in last calculation interval per job
    PUPD Percent of executions triggering database update in last calculation interval per job
    PVAX Percent of executions triggered by Alpha request in last calculation interval per job
    CPU CPU idle time (percent)
    RMX Number of bytes of CPU memory available

G.2.Async Utilties

G. Device Control and Readback (MGNT)

G.1 Message Handler

Function Code
Action
MGNT_CALB Calibrate
MGNT_DCAL Calibrate with extra diagnostics
MGNT_STDZ Standardize
MGNT_PTRB Move to a setpoint
MGNT_ZERO Zero the DAC
MGNT_CHCK Update readback in database now
MGNT_TRIM Adjust until the setpoint and readback are within tolerance
MGNT_RSET Reset hardware, restore setpoint, get readback
MGNT_TOUC Adjust only if setpoint and readback are close but not close enough
MGNT_DAOC Move to a setpoint but don't get a readback
MGNT__ACT Set setpoint to readback

G.2.Periodic Update

H. Gated ADC Acquisition (BPM)

H.1 Message Handler

Function Code
Action
BPMO_CALB_PREP Prepare for a calibration
BPMO_CALTOR_PREP Prepare for a calibration of a toroid
BPMO_CAL_RESTORE Restore a calibration
BPMO_CLR_SCP Delete structures created for a SCP
BPMO_MEAS_STOP Delete a measurement preparation
BPMO_CAN_DEF Delete a calibration
BPMO_NOGATE_PREP Prepare for a measurement of non-gated ADCs
BPMO_ACCEPT_PUBLIC Make a private calibration be public
BPMO_GETREMDAT Send next piece of large message
BPMO_BUFRING_CRE Create a ring buffer
BPMO_BUFRING_DEL Delete a ring buffer
BPMO_BUFRING_SUSP Suspend a ring buffer
BPMO_TORO_CIRC_GET Get a circular buffer of recent toroid data
BPMO_MEAS_PREP Prepare for a measurement of BPMs
BPMO_WIRE_PREP Prepare for a measurement of wire scanners
BPMO_SHO_RBUFS Return summary of existing ring buffers
BPMO_TIMING_ADJ Adjust timing values in running acquisitions

H.2 Periodic Update (if required)


SLC-Aware IOC Home Page | LCLS Controls | EPICS at SLAC | SLAC Computing | SLAC Networking | SLAC Home

Contact: Stephanie Allison
Last Modified: Nov 10, 2004