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.
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.
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.
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.
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.)
(<2-byte misc2 field>/<2-byte* object id>/<2-byte misc field>/<1-byte
*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.)
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.
- 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
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