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.
 

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.
 

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