Mooc Front-Ends

9 May 2000
Carl Schumann

Introduction

This document explains the MOOC FE infrastructure. It gives a brief explaination of what MOOC is and how it can be used to create new FEs. It also references some documents which enumerate some of the many enhancements which have been requested of the MOOC FE infrastructure.

Explaination

Basic Definitions

What is MOOC?

MOOC is an acronym for Miniumal Object-Oriented Communications. The term MOOC is commonly used to refer two things. First, MOOC can refer to a particular software library developed by Boris Lublinsky using both new and existing code from previous FE infrastructures. Second, MOOC can refer to a FE architecture which uses the MOOC library. The MOOC library gives its name to the FE architecture that it supports because it is the MOOC library which defines many of the important characteristics of a FE, e.g., SSDN format.

What is the MOOC architecture?

The defining characteristic of a FE is that it is a computer on the controls network which services some set of the FNAL data aquistion protocols, i.e., RETDAT, SETDAT, ACNET AUX, etc. This commonality of purpose means that FEs could share considerable source code. The MOOC architecture at least as extend after Boris' departure is intended to provide this common code which is augmented by individual FE programmers to create new FEs. The services provided by the MOOC architecture can be grouped into two categories. The first category is services which are FE-independent, e.g., ACNET AUX reboot, and therefore can be and are implemented entirely with in the MOOC architecture. The second category is services which are FE-dependent, e.g., RETDAT, and require some customization based on the particular FE. The FE-dependent services are customized by providing MOOC configuration values and callbacks.

The implementation of the MOOC architecture is comprised of several libraries. In addition to the MOOC library itself, the MOOC architecture requires an acnet library, t-clock library, and an ssm library. The acnet library source code is in CVS on crusher with the shortcut "acnet". This library implements the acnet protocol support upon which MOOC implements the higher-level protocols. The acnet library depends on the presence of some hardware called an SSM which it intetacts with via the ssm library. The ssm library source code is in CVS on crusher with the shortcut "ssm". The SSM hardware is no longer available, so typicaly a virtual SSM is used. But until the calls to the ssm library are removed from the acnet library FEs will need to load the ssm library. To support services like REDAT on event MOOC also needs to be able to recieve t-clock events. The reception of T-clock events requires a t-clock support library along with any hardware required by the library. The common means of recieving hardware t-clock are the VUCD/VXIUCD, IPUCD, and SLD. The VUCD/VXIUCD and IPUCD are supported by a single library, whose source code is in CVS on crusher with the shortcut "vucd". The SLD is supported by a diferent library, whose source code is in CVS on crusher with the shortcut "sld". The sld library depends on several other llibraries. Ask Rich Neswold for details. The two t-clock libraries provide the (mostly) the same set of interface routines, so that a FE programmer merely loads the library matching is hardware his hardware before loading the MOOC library. There is one module libmooc++ which allows the FE programmer to load it as one big monolith that comprises all MOOC architecture object code. This module is built by along with the mooc library proper and assumes that the FE is using a VUCD/VXIUCD or a IPUCD. The MOOC library itself is in CVS on crusher with the shortcut "mooc". All of these libraries are built for multiple processors and installed on fecode-bd in the standard way.

What is MOOCAN?

MOOCAN was the composition of two things some generally useful improvements to MOOC and code implementing the MOOC AN class callbacks. MOOCAN used to be a seperate project with its own build and source code. MOOCAN's product was a big monolith like libmooc++ which contained all MOOC architecture object code along with the AN class code. This created two difficulties. First, MOOCAN was frequently not rebuilt when the components of its monolith changed. Second, the controls department was maintaining code, i.e., the AN class code, which it did not have any expertise in.

So MOOCAN was split up. MOOCAN's generic improvements to MOOC, e.g., MoocNew(), were incorporate into MOOC proper. MOOCAN's implementation of the AN class callbacks was incorportated into the AN libraries currently maintained by Duane Voy. This gets the controls department out of the AN business.

MOOC Architecture Functionality

The various libraries contribute to the functionality of the MOOC architecture, although the most visible contribution is from the MOOC library proper. This section will provide a sketch of where particular functionality.

The acnet library provides acnet protocol services, i.e., the transmission of 2-byte quantities between acnet nodes. This service is used directly by the MOOC library and is also used by some FE applications which have FE-specific protocols, e.g., uplink. This library provides ACNET AUX functionality also. ACNET AUX is sometime referred to as ANCET level II. This libraries principle maintainer is Charlie Briegel. It is this library which services the two acnet handles ACNET and ACNET AUX.

The VUCD/VXIUCD and SLD libraries provide some routines to register callbacks which are used directly by the FE programmer. This library is what monitors the UCD hardware and informs MOOC proper that a t-clock event has occured. The libraries inform MOOC that a event has occured by calling MOOC's t_periodic() routine. In earlier, revisions of the VUCD/VXIUCD library the VUCD/VXIUCD library explicitly called MOOC's t_periodic(). Unfortunately, MOOC needed to call VUCD/VXIUCD library routines. This created a dependency which did not allow MOOC proper and the VUCD/VXIUCD libraries to be loaded independently; one had to link the together for loading into a FE. With the advent of the SLD library and the resulting need to load the t-clock support seperately from MOOC proper, this cycle needed to be broken. This was done by modifiying the VUCD/VXIUCD library to accept a callback instead of explictly calling t_periodic, this allowed the dependency to specified at run-time instead of at link-time and therefore allows one to load the SLD or VUCD/VXIUCD libraries seperately depending on what hardware is being used. The VUCD/VXIUCD library's principle maintainer is Charlie Briegel. The SLD library's principle maintainer is Rich Neswold.

The MOOC library's principle job is to marshall and unmarshall the ACNET data acquisition protocols. These protocols are described by several ACNET design notes, which were not for the most part kept current. However, as part of the initial MOOC improvement project these protocols as actually implemented were documented. These documents would be of use to anyone who needs to understand the protocols MOOC is implementing. MOOC proper services the following acnet handles.

RETDAT This handle services RETDAT requests. The routine which does the servicing is retdat() and is defined in das.c. Retdat() is a vxWorks task. This task depends on callbacks defined by the FE programmer which actually acquire the requested data based on the SSDN.

SETDAT This handle services SETDAT requests. The routine which does the servicing is setdat() and is defined in das.c. Setdat() is a vxWorks task. This task depends on callbacks defined by the FE programmer which actually issue the setting based on the SSDN and setting data.

WRITER The setdat() routine also connects to ACNET using this handle.   Setdat() uses this connection to forward sendings to SYBSET . SYBSET stores settings forwarded to it into the Sybase database. These settings will/can later retrieved by a download task, typically MISCBOOT, when a FE is booted and used to initialize the FE to its pre-reboot state. This functionality is need since most MOOC FEs do not have any kind of non-volatile storage.

FTPMAN This handle services both the FTP and snapshot plotting protocols. The routine ftpman() services this handle and is defined in ftp_init.c.   Ftpman() is also a vxWorks task.   For slower plotting frequencies ftpman does not need its own callbacks instead it can just reuse the RETDAT callbacks.   At faster frequencies the MOOC overhead for the standard RETDAT callbacks is too great and the user must provide specialized callbacks.   Even if the standard RETDAT callbacks are acceptable the FE programmer must provide configuration information about the MOOC classes' plotting capabilities.   So unfortunately the MOOC architecture does not automaticaly insure that basic plotting is supported for all MOOC classes. The FTPMAN plotting protocols is one case where the acnet design notes have been kept up to date. (Thanks to Jim Smedinghoff.)

ALARMR The routine a_alarmr() defined in alarmr.c connects to acnet with this handle.   This task is responsible for notifying AEOLUS that it is up, responding to big clears, and reporting alarms.   Note that although ALAMR is responsible for reporting alarms it does not do the alarm scan. The alarm scan is done by SLAM. SLAM then reports alarms to ALAMR via shared memory.   A_alarmr() is also a vxWorks task.   Note that ALRMR now reports alarms by device index (di), so MOOC FEs now longer need EMCs.

SLAM   The routine slam() defined in slam.c connects to acnet with this handle.   As mentioned above this task is responsible for doing the alarm scan and reporting any alarm changes to ALARMR via shared memory.   SLAM is also responsible for initiating the download. SLAM initiates the download by send a request to VAXAPM to start-up a download task, typically MISCBOOT.   When MISCBOOT is started it will poll its set of FE of which the downloading FE should be one. When the downloading FE is polled SLAM is responsible for responding to poll so that MISCBOOT will download it. MISCBOOT downloads an FE by retrieving the setting records from the Sybase database which are kept current by WRITER/SYBSET and restoring the setting values to the FE via normal SETDAT protocol. To do the alarm scan SLAM can reuse the the normal RETDAT callbacks.

MOOC API

The goal of MOOC is to facilitate control system concectivity for FEs. The principle task of the FE programmer in order to acheive conectivity is to provide code to implement new MOOC classes and to instantiate instances of these classes on FEs. The FE programmer should also provide a DABBEL template so that others or perhaps themselves can create devices in the database which access the "objects" on the FE. There is a DABBEL manual available. It should be noted that MOOC classes cannot have arbitrary interfaces, but instead are constrained to the interfaces which are built in to the control system, e.g., the power supply interface. Therefore, complex physical objects like SWICs are not modeled by a single class but by a set of related classes. Instances of each class represent a part of the total interface to a SWIC. Also, it is somewhat difficult to dynamically create and destroy objects, which means it is difficult to support both the ability that instrumentation, e.g., camac cards, can be added on the fly and the idea that MOOC objects correspond to real world objects. Thus frequently MOOC objects frequently correspond not to objects but to classes. Thus a MOOC object is in a way analogous to a CAMAC FE driver. If MOOC is used in this way there is probably only one instance of each class.

The full mooc interface is defined in mooc++.h, but the key points will be explained here. There are three aspects to writing a MOOC class. First, the basic format of the SSDN is specified by MOOC, but it is the class code which specifies the semantics of the fields in the SSDN. Second, the class code must implement the classes' callbacks and register these callbacks with MOOC. (There is one callback which is used to intialize/construct the object. There is no destructor callback.) Third, the FE programmer must call a routine to initialize MOOC. (This done once per FE.)

MOOC SSDN structure

MOOC's SSDN structure has changed over time. The basic trend has been to give the FE programmer more of the SSDN and to increase the flexibility in how fields can be used. The structure of the SSDN is given below:

(<2-byte misc2 field>/<2-byte* object id>/<2-byte misc field>/<1-byte class><1-byte channel>)
*The object id is not a full two bytes because the 3 most-significant bits are masked off. See Tim Zingelman or Rich Neswold about this trick.

The only field that MOOC itself lays claim to is the object id. MOOC uses this value to locate the callbacks which are registered for this object/device. Initailly the misc field was not fully-supported for alarmable devices. However, now that alarms are reported by di this no longer true, all fields may used without restriction. Initially, the misc2 field need to contain the FEs trunk and node. This restriction has also been lifted. Sometime the last four bytes of the SSDN are referred to as the OMSP. The second argument of the callback contains a pointer to a structure which contains among other things the values from the SSDN fields. (See mooc++.h for specifics. Look for the RS_REQ structure.)

MOOC Callbacks

Before you can associate callbacks with a class, MOOC must be informed of the classes' existence. This is done via the routine create_class(). The arguments to this routine specify the classes code(which will be used later to associate callbacks with the class), the number of callbacks, the size of this classes instance variables, and the superclasses of this class. MOOC will allocate extra storage for each superclasses' instance variables and inherit the superclass methods, but it will not initialize the superclasses instance variables. So using superclasses is error prone. It is however a necessary evil to support alarms or plotting. There is a WWW document showing how the instance variables of the derived and superclasses are layed out. It is important to understand this layout when initializing the superclasses' instance variables in the initialization callback.

The possible MOOC callbacks are a fixed set enumerated in mooc++.h by the m_type enum. The key callbacks/methods are the ones which correspond directly to a SETDAT or RETDAT request for an acnet property and the initialization callback. The callbacks are listed below.

Init - construction/initialization of an object

rPRBSTS - read(RETDAT) the basic status

rPRREAD - read(RETDAT) the reading

rPRSET - read(RETDAT) the setting

sPRBCTL - set(SETDAT) the basic control

sPRSET - set(SETDAT) the setting

Callbacks are registered with MOOC via the add_class_msg() routine. This routine takes a class number, a callback enumeration value, and a pointer to the callback function. As with all functions discussed here, see mooc++.h for more details.

Objects are created with the routine create_instance(). This routine will allocate storage for the object's instance variables and call the most derived classes initialization callback if one exists. The most derived class must initialize everybody which is of course not very encapsulated. If you want to support alarms or plotting you will need to do this. Example code is very useful in getting this right, but you will have to adjust some of the alarm and plotting instance variables to suit the particular class being developed. In addition to MOOC issues

MOOC Initialization

MoocNew() needs called before any other MOOC routines. This routine will initialize some MOOC data structures, define the alarm and plotting superclasses, and create the guaranteed readable and settable devices. There is a template for these guaranteed devices. However, someone still needs to DABBEL in the devices and enter them on D98 on a FE by FE basis.

Requested MOOC Enhancements

MOOC wish list

Potential FE services

Security, Privacy, Legal